<pclass="last">This tutorial should be read side-by-side with the Sphinc source
for this document (see <aclass="reference internal" href="#ipython-literal"><em>Sphinx source for this tutorial</em></a>) because otherwise
you will see only the rendered output and not the code that
generated it. Excepting the example above, we will not in general
be showing the liuteral rest in this document that generates the
rendered output.</p>
</div>
<p>The state from previous sessions is stored, and standard error is
trapped. At doc build time, ipython’s output and std err will be
inserted, and prompts will be renumbered. So the prompt below should
be renumbered in the rendered docs, and pick up where the block above
left off.</p>
<divclass="highlight-ipython"><divclass="highlight"><pre><spanclass="gp">In [3]: </span><spanclass="n">z</span><spanclass="o">=</span><spanclass="n">x</span><spanclass="o">*</span><spanclass="mi">3</span><spanclass="c"># x is recalled from previous block</span>
<spanclass="gp">In [6]: </span><spanclass="n">q</span><spanclass="o">=</span><spanclass="n">z</span><spanclass="p">[)</span><spanclass="c"># this is a syntax error -- we trap ipy exceptions</span>
<spanclass="go"> File "<ipython-input-6-9e4a6c3ff9f7>", line 1</span>
<spanclass="go"> q = z[) # this is a syntax error -- we trap ipy exceptions</span>
<p>Most of the “pseudo-decorators” can be used an options to ipython
mode. For example, to setup matplotlib pylab but suppress the output,
you can do. When using the matplotlib <ttclass="docutils literal"><spanclass="pre">use</span></tt> directive, it should
occur before any import of pylab. This will not show up in the
rendered docs, but the commands will be executed in the embedded
interpreter and subsequent line numbers will be incremented to reflect
the inputs:</p>
<divclass="highlight-python"><pre>.. ipython::
:suppress:
In [144]: from pylab import *
In [145]: ion()</pre>
</div>
<p>Likewise, you can set <ttclass="docutils literal"><spanclass="pre">:doctest:</span></tt> or <ttclass="docutils literal"><spanclass="pre">:verbatim:</span></tt> to apply these
<h2>Pseudo-Decorators<aclass="headerlink" href="#pseudo-decorators" title="Permalink to this headline">¶</a></h2>
<p>Here are the supported decorators, and any optional arguments they
take. Some of the decorators can be used as options to the entire
block (eg <ttclass="docutils literal"><spanclass="pre">verbatim</span></tt> and <ttclass="docutils literal"><spanclass="pre">suppress</span></tt>), and some only apply to the
line just below them (eg <ttclass="docutils literal"><spanclass="pre">savefig</span></tt>).</p>
<p>@suppress</p>
<blockquote>
<div>execute the ipython input block, but suppress the input and output
block from the rendered output. Also, can be applied to the entire
<ttclass="docutils literal"><spanclass="pre">..ipython</span></tt> block as a directive option with <ttclass="docutils literal"><spanclass="pre">:suppress:</span></tt>.</div></blockquote>
<p>@verbatim</p>
<blockquote>
<div>insert the input and output block in verbatim, but auto-increment
the line numbers. Internally, the interpreter will be fed an empty
string, so it is a no-op that keeps line numbering consistent.
Also, can be applied to the entire <ttclass="docutils literal"><spanclass="pre">..ipython</span></tt> block as a
directive option with <ttclass="docutils literal"><spanclass="pre">:verbatim:</span></tt>.</div></blockquote>
<p>@savefig OUTFILE [IMAGE_OPTIONS]</p>
<blockquote>
<div>save the figure to the static directory and insert it into the
document, possibly binding it into a minipage and/or putting
code/figure label/references to associate the code and the
figure. Takes args to pass to the image directive (<em>scale</em>,
<em>width</em>, etc can be kwargs); see <aclass="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#image">image options</a>
for details.</div></blockquote>
<p>@doctest</p>
<blockquote>
<div>Compare the pasted in output in the ipython block with the output
generated at doc build time, and raise errors if they don’t
match. Also, can be applied to the entire <ttclass="docutils literal"><spanclass="pre">..ipython</span></tt> block as a
directive option with <ttclass="docutils literal"><spanclass="pre">:doctest:</span></tt>.</div></blockquote>
<spanid="ipython-literal"></span><h2>Sphinx source for this tutorial<aclass="headerlink" href="#sphinx-source-for-this-tutorial" title="Permalink to this headline">¶</a></h2>