This is a useful feature I've wanted myself. I just contributed a
change to the plot directive in svn to support this using two new
options :context: and :nofigs:, and updated the sampledoc tutorial.
The relevant bit from the tutorial is in the link below:
···
On Mon, Nov 8, 2010 at 6:55 PM, Matthew Brett <matthew.brett@...149...> wrote:
First - thank you - it makes my heart very glad to be able to do this:
.. plot::
:include-source:
import matplotlib.pyplot as plt
plt.plot(range(10))
plt.show()
Here's my question. This is already a huge step forward for me, but
the full monty would be to be able to do:
.. testcode::
import some_module
res = some_module.use_it('a string')
.. plot::
:include-source:
plt.imshow(res)
and so on. I mean, the ability to keep the code context across the
page, both in the ..plot: and ..testcode:: and even >>> directives, so
I can build up my tutorial examples on top of the previous results.
That step would make it the perfect tool for the tutorials that I have
ready to port - and I am sure - many others.
Is that already possible? If not, how easy would it be? It if isn't
easy, can y'all give me some pointers as to how to get there?
=================
Ipython Directive
The ipython directive is a stateful ipython shell for embedding in
sphinx documents. It knows about standard ipython prompts, and
extracts the input and output lines. These prompts will be renumbered
starting at ``1``. The inputs will be fed to an embedded ipython
interpreter and the outputs from that interpreter will be inserted as
well.
.. ipython::
In [136]: x = 2
In [137]: x**3
Out[137]: 8
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 ``In [3]:`` in the rendered docs.
.. ipython::
In [138]: z = x*3 # x is recalled from previous block
In [139]: z
Out[139]: 6
In [140]: print z
--------> print(z)
6
In [141]: q = z[) # this is a syntax error -- we trap ipy exceptions
------------------------------------------------------------
File "<ipython console>", line 1
q = z[) # this is a syntax error -- we trap ipy exceptions
^
SyntaxError: invalid syntax
The embedded interpeter supports some limited markup. For example,
you can put comments in your ipython sessions, which are reported
verbatim. There are some handy "pseudo-decorators" that let you
doctest the output. The inputs are fed to an embbedded ipython
session and the outputs from the ipython session are inserted into
your doc. If the output in your doc and in the ipython session don't
match on a doctest assertion, an error will be
.. ipython::
In [1]: x = 'hello world'
# this will raise an error if the ipython output is different
@doctest
In [2]: x.upper()
Out[2]: 'HELLO WORLD'
# some readline features cannot be supported, so we allow
# "verbatim" blocks, which are dumped in verbatim except prompts
# are continuously numbered
@verbatim
In [3]: x.st<TAB>
x.startswith x.strip
Multi-line input is supported.
.. ipython::
In [130]: url = 'http://ichart.finance.yahoo.com/table.csv?s=CROX\\
.....: &d=9&e=22&f=2009&g=d&a=1&br=8&c=2006&ignore=.csv'
In [131]: print url.split('&')
--------> print(url.split('&'))
['http://ichart.finance.yahoo.com/table.csv?s=CROX’, 'd=9', 'e=22',
'f=2009', 'g=d', 'a=1', 'b=8', 'c=2006', 'ignore=.csv']
In [60]: import urllib
You can do doctesting on multi-line output as well. Just be careful
when using non-deterministic inputs like random numbers in the ipython
directive, because your inputs are ruin through a live interpreter, so
if you are doctesting random output you will get an error. Here we
"seed" the random number generator for deterministic output, and we
suppress the seed line so it doesn't show up in the rendered output
.. ipython::
In [133]: import numpy.random
@suppress
In [134]: numpy.random.seed(2358)
@doctest
In [135]: np.random.rand(10,2)
Out[135]:
array([[ 0.64524308, 0.59943846],
[ 0.47102322, 0.8715456 ],
[ 0.29370834, 0.74776844],
[ 0.99539577, 0.1313423 ],
[ 0.16250302, 0.21103583],
[ 0.81626524, 0.1312433 ],
[ 0.67338089, 0.72302393],
[ 0.7566368 , 0.07033696],
[ 0.22591016, 0.77731835],
[ 0.0072729 , 0.34273127]])
Another demonstration of multi-line input and output
.. ipython::
In [106]: print x
--------> print(x)
jdh
In [109]: for i in range(10):
.....: print i
.....:
.....:
0
1
2
3
4
5
6
7
8
9
Most of the "pseudo-decorators" can be used an options to ipython
mode. For example, to setup maptlotlib pylab but suppress the output,
you can do. When using the matplotlib ``use`` 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
interpeter and subsequent line numbers will be incremented to reflect
the inputs::
.. ipython::
:suppress:
In [144]: from pylab import *
In [145]: ion()
.. ipython::
:suppress:
In [144]: from pylab import *
In [145]: ion()
Likewise, you can set ``:doctest:`` or ``:verbatim:`` to apply these
settings to the entire block.
You can create one or more pyplot plots and insert them with the
``@savefig`` decorator.
.. ipython::
@savefig plot_simple.png width=4in
In [151]: plot([1,2,3]);
# use a semicolon to suppress the output
@savefig hist_simple.png width=4in
In [151]: hist(np.random.randn(10000), 100);
In a subsequent session, we can update the current figure with some
text, and then resave
.. ipython::
In [151]: ylabel('number')
In [152]: title('normal distribution')
@savefig hist_with_text.png
In [153]: grid(True)