[Numpy-discussion] Plot directive in numpy docs
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
import matplotlib.pyplot as plt
x = np.linspace(0, 2*pi, 200)
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.
More information about the Numpy-discussion