[SciPy-dev] On scipy/numpy documentation, and executing code in docstrings
Wed Aug 5 15:32:13 CDT 2009
On 2009-08-05, Emmanuelle Gouillart <email@example.com> wrote:
> Hello list,
> disclaimer: I don't have much hindsight about what I'm talking
> about in the following, so I apologize if it doesn't make much sense...
> My question is: is there some way (apart from copy-and-paste :D)
> to execute some of the code inside docstrings, in order e.g. to generate
> pylab plots? This may be a useful feature for the documentation of scipy:
> indeed, a plot may speak for itself better than long explanations about
> the output of scipy's algorithms. Some docstrings already include calls
> to plotting commands (one example:
> but of course, the plots are not created while viewing the help.
The plots do appear in the final documentation, cf.
(The scipy.stats.distributions examples are not actually
executable Python code, being more pseudo-codeish. This could and
probably should be fixed, though.)
It's not really feasible to have them appear in the doc editor --
there's no reliable & easy way to sandbox Python code, and I'm
not comfortable with having a way to run potentially untrusted
code on the servers.
One thing that I'm not very happy with the Sphinx output is that
copy & paste of the examples is quite difficult, since you get
the >>> and ... prompts. This could be avoided with suitable HTML
> Maybe it's a stupid idea, but I'm thinking about a %demo magic
> function in Ipython that would print the docstring of an object and
> execute the code of the docstring (preferably in a separate namespace)
> and, in particular, display pylab's windows.
> Does such a feature already exist somewhere? If not, do you see
> any interest in coding it? Matplotlib and Mayavi2 call special demo
> functions and it would be possible to do the same for scipy, but on the
> other side, using directly the docstrings for demos might be just as
I think such a demo function could be easy to implement: just
pick up the doctest lines and run them. I think a IPython
extension could easily be written for this: just check what's in
the ipy_*.py files under IPython/Extensions and adapt one of
There's a ready-made implementation of the doctest pickup in
plot_directive.py under numpy/doc/sphinxext.
More information about the Scipy-dev