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

Emmanuelle Gouillart emmanuelle.gouillart@normalesup....
Wed Aug 5 13:43:42 CDT 2009


	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. 

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

	Regards,

	Emmanuelle

	 



More information about the Scipy-dev mailing list