<spanid="extensions"></span><h1>Sphinx extensions for embedded plots, math and more<aclass="headerlink" href="#sphinx-extensions-for-embedded-plots-math-and-more" title="Permalink to this headline">¶</a></h1>
<p>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 <ttclass="file docutils literal"><spanclass="pre">sphinxext</span></tt>
directory from git (see <aclass="reference internal" href="getting_started.html#fetching-the-data"><em>Fetching the data</em></a>), and install them in
<p>Now let’s look at some of these in action. You can see the literal
source for this file at <emclass="xref std std-ref">extensions-literal</em>.</p>
<divclass="section" id="ipython-sessions">
<spanid="ipython-highlighting"></span><h2>ipython sessions<aclass="headerlink" href="#ipython-sessions" title="Permalink to this headline">¶</a></h2>
<p>Michael Droettboom contributed a sphinx extension which does <aclass="reference external" href="http://pygments.org">pygments</a> syntax highlighting on <aclass="reference external" href="http://ipython.scipy.org">ipython</a> sessions. Just use ipython as the
language in the <ttclass="docutils literal"><spanclass="pre">sourcecode</span></tt> directive:</p>
<imgsrc="_images/mathmpl/math-d9a8b00dd5.png" class="center" /><p>This documentation framework includes a Sphinx extension,
<ttclass="file docutils literal"><spanclass="pre">sphinxext/mathmpl.py</span></tt>, 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 <ttclass="docutils literal"><spanclass="pre">mathmpl</span></tt> to the list of
extensions in <ttclass="file docutils literal"><spanclass="pre">conf.py</span></tt>.</p>
<p>Current SVN versions of Sphinx now include built-in support for math.
There are two flavors:</p>
<blockquote>
<div><ulclass="simple">
<li>pngmath: uses dvipng to render the equation</li>
<li>jsmath: renders the math in the browser using Javascript</li>
</ul>
</div></blockquote>
<p>To use these extensions instead, add <ttclass="docutils literal"><spanclass="pre">sphinx.ext.pngmath</span></tt> or
<ttclass="docutils literal"><spanclass="pre">sphinx.ext.jsmath</span></tt> to the list of extensions in <ttclass="file docutils literal"><spanclass="pre">conf.py</span></tt>.</p>
<p>All three of these options for math are designed to behave in the same
way.</p>
<p>See the matplotlib <aclass="reference external" href="http://matplotlib.sourceforge.net/users/mathtext.html">mathtext guide</a> for lots
more information on writing mathematical expressions in matplotlib.</p>
<spanid="pyplots"></span><h2>Inserting matplotlib plots<aclass="headerlink" href="#inserting-matplotlib-plots" title="Permalink to this headline">¶</a></h2>
<p>Inserting automatically-generated plots is easy. Simply put the
script to generate the plot in the <ttclass="file docutils literal"><spanclass="pre">pyplots</span></tt> directory, and
refer to it using the <ttclass="docutils literal"><spanclass="pre">plot</span></tt> directive. First make a
<ttclass="file docutils literal"><spanclass="pre">pyplots</span></tt> directory at the top level of your project (next to
:<ttclass="docutils literal"><spanclass="pre">conf.py</span></tt>) and copy the <ttclass="file docutils literal"><spanclass="pre">ellipses.py`</span></tt> file into it:</p>
<pid="extensions-literal">See the <aclass="reference internal" href="ipython_directive.html#ipython-directive"><em>Ipython Directive</em></a> for a tutorial on embedding stateful,
matplotlib aware ipython sessions into your rest docs with multiline
and doctest support.</p>
</div>
<divclass="section" id="this-file">
<h2>This file<aclass="headerlink" href="#this-file" title="Permalink to this headline">¶</a></h2>