matplotlib Code

Brought to you by: cjgohlke, dsdale, efiring, heeres, and 8 others

[r7476]: / trunk / sampledoc_tut / extensions.rst Maximize Restore History

220 lines (150 with data), 6.8 kB

Sphinx extensions for embedded plots, math and more

Sphinx is written in python, and supports the ability to write custom extensions. We've written a few for the matplotlib documentation, some of which are part of matplotlib itself in the matplotlib.sphinxext module, some of which are included only in the sphinx doc directory, and there are other extensions written by other groups, eg numpy and ipython. We're collecting these in this tutorial and showing you how to install and use them for your own project. First let's grab the python extension files from the :file:`sphinxext` directory from svn (see :ref:`fetching-the-data`), and install them in our :file:`sampledoc` project :file:`sphinxext` directory:

home:~/tmp/sampledoc> mkdir sphinxext
home:~/tmp/sampledoc> cp ../sampledoc_tut/sphinxext/*.py sphinxext/
home:~/tmp/sampledoc> ls sphinxext/
apigen.py             inheritance_diagram.py
docscrape.py          ipython_console_highlighting.py
docscrape_sphinx.py   numpydoc.py

In addition to the builtin matplotlib extensions for embedding pyplot plots and rendering math with matplotlib's native math engine, we also have extensions for syntax highlighting ipython sessions, making inhertiance diagrams, and more.

We need to inform sphinx of our new extensions in the :file:`conf.py` file by adding the following. First we tell it where to find the extensions:

# If your extensions are in another directory, add it here. If the
# directory is relative to the documentation root, use
# os.path.abspath to make it absolute, like shown here.
sys.path.append(os.path.abspath('sphinxext'))

And then we tell it what extensions to load:

# Add any Sphinx extension module names here, as strings. They can
# be extensions coming with Sphinx (named 'sphinx.ext.*') or your
# custom ones.
extensions = ['matplotlib.sphinxext.mathmpl',
          'matplotlib.sphinxext.only_directives',
          'matplotlib.sphinxext.plot_directive',
          'sphinx.ext.autodoc',
          'sphinx.ext.doctest',
          'ipython_console_highlighting',
          'inheritance_diagram',
          'numpydoc']

Now let's look at some of these in action. You can see the literal source for this file at :ref:`extensions-literal`.

ipython sessions

Michael Droettboom contributed a sphinx extension which does pygments syntax highlighting on ipython sessions. Just use ipython as the language in the sourcecode directive:

.. sourcecode:: ipython

    In [69]: lines = plot([1,2,3])

    In [70]: setp(lines)
      alpha: float
      animated: [True | False]
      antialiased or aa: [True | False]
      ...snip

and you will get the syntax highlighted output below.

In [69]: lines = plot([1,2,3])

In [70]: setp(lines)
  alpha: float
  animated: [True | False]
  antialiased or aa: [True | False]
  ...snip

This support is included in this template, but will also be included in a future version of Pygments by default.

Using math

In sphinx you can include inline math x ← y x∀y x − y or display math

W^3β_{δ₁ρ₁σ₂} = U^3β_δ₁ρ₁ + (1)/(8π2)^α₂∫_α₂dα^′₂⎡⎣(U^2β_δ₁ρ₁ − α^′₂U^1β_ρ₁σ₂)/(U^0β_ρ₁σ₂)⎤⎦

To include math in your document, just use the math directive; here is a simpler equation:

.. math::

  W^{3\beta}_{\delta_1 \rho_1 \sigma_2} \approx U^{3\beta}_{\delta_1 \rho_1}

which is rendered as

W^3β_{δ₁ρ₁σ₂} ≈ U^3β_δ₁ρ₁

This documentation framework includes a Sphinx extension, :file:`sphinxext/mathmpl.py`, that uses matplotlib to render math equations when generating HTML, and LaTeX itself when generating a PDF. This can be useful on systems that have matplotlib, but not LaTeX, installed. To use it, add mathmpl to the list of extensions in :file:`conf.py`.

Current SVN versions of Sphinx now include built-in support for math. There are two flavors:

pngmath: uses dvipng to render the equation

jsmath: renders the math in the browser using Javascript

To use these extensions instead, add sphinx.ext.pngmath or sphinx.ext.jsmath to the list of extensions in :file:`conf.py`.

All three of these options for math are designed to behave in the same way.

See the matplotlib mathtext guide for lots more information on writing mathematical expressions in matplotlib.

Inserting matplotlib plots

Inserting automatically-generated plots is easy. Simply put the script to generate the plot in the :file:`pyplots` directory, and refer to it using the plot directive. To include the source code for the plot in the document, pass the include-source parameter:

.. plot:: pyplots/ellipses.py
   :include-source:

In the HTML version of the document, the plot includes links to the original source code, a high-resolution PNG and a PDF. In the PDF version of the document, the plot is included as a scalable PDF.

You can also inline simple plots, and the code will be executed at documentation build time and the figure inserted into your docs; the following code:

.. plot::

   import matplotlib.pyplot as plt
   import numpy as np
   x = np.random.randn(1000)
   plt.hist( x, 20)
   plt.grid()
   plt.title(r'Normal: $\mu=%.2f, \sigma=%.2f$'%(x.mean(), x.std()))
   plt.show()

produces this output:

See the matplotlib pyplot tutorial and the gallery for lots of examples of matplotlib plots.

Inheritance diagrams

Inheritance diagrams can be inserted directly into the document by providing a list of class or module names to the inheritance-diagram directive.

For example:

.. inheritance-diagram:: codecs

produces: