[SciPy-dev] On scipy/numpy documentation, and executing code in docstrings

Pauli Virtanen pav+sp@iki...
Wed Aug 5 15:32:13 CDT 2009

On 2009-08-05, Emmanuelle Gouillart <emmanuelle.gouillart@normalesup.org> 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:
> http://docs.scipy.org/scipy/docs/scipy.stats.distributions.poisson/),
> 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
> well... 

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.

Pauli Virtanen

More information about the Scipy-dev mailing list