![](https://secure.gravatar.com/avatar/8073ab54b7a56c709a8f48f17b721bdf.jpg?s=120&d=mm&r=g)
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. 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