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

[Pauli Virtanen]

On 2009-08-05, Emmanuelle Gouillart <emmanuelle.gouillart at 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. 
http://docs.scipy.org/doc/numpy/reference/generated/numpy.random.gamma.html

(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 
magick.

> 	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 
them.

There's a ready-made implementation of the doctest pickup in 
plot_directive.py under numpy/doc/sphinxext.

-- 
Pauli Virtanen