plot directive in reST tutorials

Development matplotlib-devel
#1

Howdy,

recently, Matthew Brett pointed out that reST supports a mode that's
very handy for writing tutorial-like documents that contain code
blocks including their output, and they can even be run as tests.
Here's a simple example with its corresponding source:

http://neuroimaging.scipy.org/site/doc/manual/html/users/analysis_pipeline.html
http://neuroimaging.scipy.org/site/doc/manual/html/_sources/users/analysis_pipeline.txt

and they can even use the MPL math support, as seen here:

http://neuroimaging.scipy.org/site/doc/manual/html/users/glm_spec.html
http://neuroimaging.scipy.org/site/doc/manual/html/_sources/users/glm_spec.txt

But we were thinking it would be great to have also plot support for
this, without being forced to use standalone scripts like in mpl's
current form of the plot directive. I unfortunately have to go now
and will be mostly offline for a week, but I just had a chat about
this with John, so I want to leave some context in here in case this
is of interest to you guys. If there's a discussion on the API, I'll
do my best to keep up, but I'm also cc'ing the nipy list so those
interested can pitch in (though we should keep the conversation to the
MPL list, where the plot machinery is implemented).

Cheers,

f

#2

Has anyone else had a chance to look at this? It seems fairly straightforward and I may have a go at this this morning if no one else has already.

Mike

Fernando Perez wrote:

···

Howdy,

recently, Matthew Brett pointed out that reST supports a mode that's
very handy for writing tutorial-like documents that contain code
blocks including their output, and they can even be run as tests.
Here's a simple example with its corresponding source:

http://neuroimaging.scipy.org/site/doc/manual/html/users/analysis_pipeline.html
http://neuroimaging.scipy.org/site/doc/manual/html/_sources/users/analysis_pipeline.txt

and they can even use the MPL math support, as seen here:

http://neuroimaging.scipy.org/site/doc/manual/html/users/glm_spec.html
http://neuroimaging.scipy.org/site/doc/manual/html/_sources/users/glm_spec.txt

But we were thinking it would be great to have also plot support for
this, without being forced to use standalone scripts like in mpl's
current form of the plot directive. I unfortunately have to go now
and will be mostly offline for a week, but I just had a chat about
this with John, so I want to leave some context in here in case this
is of interest to you guys. If there's a discussion on the API, I'll
do my best to keep up, but I'm also cc'ing the nipy list so those
interested can pitch in (though we should keep the conversation to the
MPL list, where the plot machinery is implemented).

Cheers,

f

------------------------------------------------------------------------------
Create and Deploy Rich Internet Apps outside the browser with Adobe(R)AIR(TM)
software. With Adobe AIR, Ajax developers can use existing skills and code to
build responsive, highly engaging applications that combine the power of local
resources and data with the reach of the web. Download the Adobe AIR SDK and
Ajax docs to start building applications today-http://p.sf.net/sfu/adobe-com
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

#3

A preliminary version of this is committed on the branch and trunk.

You can now do:

.. plot::

     from matplotlib.pyplot import *
     plot([1,2,3])

One open API question is whether to implicitly "from matplotlib.pyplot import *" or "from matplotlib import pyplot as plt" or nothing. I generally don't like "import *" or implicit things, so I've decided to do none of the above. But I could see how it might be nice to reduce the verbosity of these little code examples to import something be default. Let me know if you feel strongly about changing it.

It has also been moved to the installed source directory, so other projects no longer need to copy it. Just change the entry in the extensions list in the Sphinx conf.py from 'plot_directive' to 'matplotlib.sphinxext.plot_directive' and remove your local copy of the extension.

Mike

Michael Droettboom wrote:

···

Has anyone else had a chance to look at this? It seems fairly straightforward and I may have a go at this this morning if no one else has already.

Mike

Fernando Perez wrote:
  

Howdy,

recently, Matthew Brett pointed out that reST supports a mode that's
very handy for writing tutorial-like documents that contain code
blocks including their output, and they can even be run as tests.
Here's a simple example with its corresponding source:

http://neuroimaging.scipy.org/site/doc/manual/html/users/analysis_pipeline.html
http://neuroimaging.scipy.org/site/doc/manual/html/_sources/users/analysis_pipeline.txt

and they can even use the MPL math support, as seen here:

http://neuroimaging.scipy.org/site/doc/manual/html/users/glm_spec.html
http://neuroimaging.scipy.org/site/doc/manual/html/_sources/users/glm_spec.txt

But we were thinking it would be great to have also plot support for
this, without being forced to use standalone scripts like in mpl's
current form of the plot directive. I unfortunately have to go now
and will be mostly offline for a week, but I just had a chat about
this with John, so I want to leave some context in here in case this
is of interest to you guys. If there's a discussion on the API, I'll
do my best to keep up, but I'm also cc'ing the nipy list so those
interested can pitch in (though we should keep the conversation to the
MPL list, where the plot machinery is implemented).

Cheers,

f

------------------------------------------------------------------------------
Create and Deploy Rich Internet Apps outside the browser with Adobe(R)AIR(TM)
software. With Adobe AIR, Ajax developers can use existing skills and code to
build responsive, highly engaging applications that combine the power of local
resources and data with the reach of the web. Download the Adobe AIR SDK and
Ajax docs to start building applications today-http://p.sf.net/sfu/adobe-com
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

#4

Hi guys,

You can now do:

.. plot::

    from matplotlib.pyplot import *
    plot([1,2,3])

This is very nice - thank you for doing that.

But, thinking about the online tutorials, you often want to do
something as you can do with the sourcecode directive, as in:

.. testcode::

   import numpy as np
   print np.inf

Some text then

.. testoutput::

   inf

More text

.. testcode::

   # I still have the context from the blocks above
   print np.nan

More text

.. testoutput::

   nan

In that way, I can build up a tutorial, setting and calculating
variables, doing plots as I go, without having to recreate the
calculations at each step.

Is it possible to make the ..plot directive pick up the context in the same way?

Thanks a lot,

Matthew

#5

That's a great suggestion. I'm not familiar at all with the doc test extension, so the plot directive doesn't do this. It gets a fresh namespace (though not a fresh interpreter) for each plot.

To avoid complicating the merge further, I'd like to wait for Pauli Vertanen's merge of the new plot directive features from Numpy back into matplotlib before looking at implementing this. It will probably just involve inheriting/emulating whatever the doctest extension is doing to make that work. And if the directive is used in the old way (providing a filename), we'll just clear any state at that point.

Mike

Matthew Brett wrote:

···

Hi guys,

You can now do:

.. plot::

    from matplotlib.pyplot import *
    plot([1,2,3])
    
This is very nice - thank you for doing that.

But, thinking about the online tutorials, you often want to do
something as you can do with the sourcecode directive, as in:

.. testcode::

   import numpy as np
   print np.inf

Some text then

.. testoutput::

   inf

More text

.. testcode::

   # I still have the context from the blocks above
   print np.nan

More text

.. testoutput::

   nan

In that way, I can build up a tutorial, setting and calculating
variables, doing plots as I go, without having to recreate the
calculations at each step.

Is it possible to make the ..plot directive pick up the context in the same way?

Thanks a lot,

Matthew
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA