[Numpy-discussion] Plot directive in numpy docs

Pauli Virtanen pav@iki...
Fri Dec 12 08:09:14 CST 2008

Fri, 12 Dec 2008 14:20:50 +0100, Gael Varoquaux wrote:
> What is the guideline on using the plot directive in the numpy docs? It
> can make some examples much easier to understand, but on the other hand,
> it can clutter the docstrings. In addition, I am not sure how our
> documentation pipeline deals with it.

No guideline yet, I'd suggest not to use it in docstrings yet, before we 
are sure it works as we want it to work.

It does not (and probably will not, due to security reasons) work in the 
wiki. But it already works in the built documentation.

** How it works now

.. plot::

   import matplotlib.pyplot as plt
   x = np.linspace(0, 2*pi, 200)
   plt.plot(x, np.sin(x))

assuming "import numpy as np" is pre-defined in a Sphinx conf.py 

The code can either be in doctest format or not, this is automatically 
detected. Each matplotlib figure gets a separate image, for examples see 
the Scipy Tutorial. The code is executed and images are automatically 
captured into files when the documentation is built. (No need to use eg. 

The code inside the plot:: directive cannot, due to technical reasons, 
access any variables etc. used in preceding doctests.

** What to think about

- Should docstrings be assumed by default to lie inside plot:: directive,
  unless a plot:: directive is explicitly used?

  This way the plot could use stuff defined in earlier examples.

- Or, maybe only the examples section should assumed to be in a plot::
  by default, if it contains doctests.

  I'd think this would be a good idea. This way, we could continue using
  the current docstring standard, and be able to generate figures from
  the examples that use matplotlib.

- I don't think the plot:: directive itself adds much line noise to the
  docstrings, but maybe some differ.

- Where to allow plots in docstrings. I'd guess only in the examples

- Whether to use doctest notation inside plot:: or not.

- Our security model should continue to be as previously:
  the person who checks in docstrings from the wiki to SVN checks that
  the doctests do not contain malicious code.

- We have technical leeway to do many things, because Sphinx allows
  us to preprocess docstrings in any way we want before processing them.


There was the unresolved question about should the example codes be run
when numpy.test() is run, and what to do with matplotlib code in this
case. The main problem was that if the plot codes are picked up as 
doctests, then the matplotlib objects returned by pyplot functions cause 
unnecessary line noise. Definitely, any doctest markup should be avoided 
in the examples. So the options were either to implement some magic to 
skip offending doctest lines, or to not use doctest markup for plots.

Pauli Virtanen

More information about the Numpy-discussion mailing list