plot directive, thank you and a question

Hi,

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?

Thanks again,

Matthew

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:

  http://matplotlib.sourceforge.net/sampledoc/extensions.html#inserting-matplotlib-plots

Also, we have a really useful ipython directive that is stateful by
default, and includes many options for suppressing input blocks,
doctesting on output blocks, saving figures, and more. It is included
in the ipython src tree. My original proposal is at
http://matplotlib.sourceforge.net/ipymode/_build/html/proposal.html,
which I've implemented with minor changes. A real world working
example from some lecture notes I prepared recently is attached as
convolution.rst, and some notes are below. I need to get this added
to the sampledoc tutorial....

convolution.rst (7.01 KB)

···

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)

Hi,

...

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?

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:

http://matplotlib.sourceforge.net/sampledoc/extensions.html#inserting-matplotlib-plots

Also, we have a really useful ipython directive that is stateful by
default, and includes many options for suppressing input blocks,
doctesting on output blocks, saving figures, and more. It is included
in the ipython src tree. My original proposal is at
http://matplotlib.sourceforge.net/ipymode/_build/html/proposal.html,
which I've implemented with minor changes. A real world working
example from some lecture notes I prepared recently is attached as
convolution.rst, and some notes are below. I need to get this added
to the sampledoc tutorial....

Thanks for extensions, and the pointer to the ipython directive, I had
only half remembered it, but it does look very well designed for what
I had in mind.

For the first time for a few years, I'm looking forward to writing
some tutorials...

See you,

Matthew

···

On Mon, Nov 8, 2010 at 7:06 PM, John Hunter <jdh2358@...149...> wrote:

On Mon, Nov 8, 2010 at 6:55 PM, Matthew Brett <matthew.brett@...149...> wrote: