On scipy/numpy documentation, and executing code in docstrings
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
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
Hi Pauli, thanks for your answer!
The plots do appear in the final documentation, cf. http://docs.scipy.org/doc/numpy/reference/generated/numpy.random.gamma.html
True! I hadn't noticed as I usually use only Ipython's help, but the html pages look really nice with the plots.
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.
Sure, I wasn't talking about having them appear in the doc editor. We can afford doing some copy & paste while using the doc editor, I think...
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 the wonderful %doctest_mode magic command of Ipython should be advertised somewhere... I use it all the time since I've discovered the feature, it's awfully convenient :D.
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.
That's exactly the kind of hints I was looking for, many thanks! I'll have a look at the files you mention to see how it could be done. Cheers, Emmanuelle
On Wed, Aug 5, 2009 at 1:49 PM, Emmanuelle Gouillart<emmanuelle.gouillart@normalesup.org> wrote:
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 the wonderful %doctest_mode magic command of Ipython should be advertised somewhere... I use it all the time since I've discovered the feature, it's awfully convenient :D.
Thanks for answering for me :) Regarding the advertising, I'll be the first to admit we could do better. But in our defense, it's at least documented: http://ipython.scipy.org/doc/stable/html/interactive/tutorial.html?highlight... http://ipython.scipy.org/doc/stable/html/overview.html?highlight=doctest_mod... http://ipython.scipy.org/doc/stable/html/development/overview.html?highlight... http://ipython.scipy.org/doc/stable/html/api/generated/IPython.Magic.html?hi... Maybe ipython should open a twitter account with a tweet-tip (tweetip?) of the day everyday :)
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.
That's exactly the kind of hints I was looking for, many thanks! I'll have a look at the files you mention to see how it could be done.
And when you finish, send it our way. Operators are standing by to take your patch and your credit card number... :) Take care, f
On Wed, Aug 5, 2009 at 17:38, Fernando Perez<fperez.net@gmail.com> wrote:
On Wed, Aug 5, 2009 at 1:49 PM, Emmanuelle Gouillart<emmanuelle.gouillart@normalesup.org> wrote:
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.
That's exactly the kind of hints I was looking for, many thanks! I'll have a look at the files you mention to see how it could be done.
And when you finish, send it our way. Operators are standing by to take your patch and your credit card number... :)
Something like this? In [1]: %run_examples np.broadcast Produce an object that mimics broadcasting. Parameters ---------- in1, in2, ... : array_like Input parameters. Returns ------- b : broadcast object Broadcast the input parameters against one another, and return an object that encapsulates the result. Amongst others, it has ``shape`` and ``nd`` properties, and may be used as an iterator. Examples -------- Manually adding two vectors, using broadcasting:
x = np.array([[1], [2], [3]]) Press <q> to quit, <Enter> to execute...
y = np.array([4, 5, 6]) Press <q> to quit, <Enter> to execute...
b = np.broadcast(x, y) Press <q> to quit, <Enter> to execute...
out = np.empty(b.shape) Press <q> to quit, <Enter> to execute...
out.flat = [u+v for (u,v) in b] Press <q> to quit, <Enter> to execute...
out array([[ 5., 6., 7.], [ 6., 7., 8.], [ 7., 8., 9.]])
Press <q> to quit, <Enter> to execute... output: array([[ 5., 6., 7.], [ 6., 7., 8.], [ 7., 8., 9.]]) Compare against built-in broadcasting:
x + y array([[5, 6, 7], [6, 7, 8], [7, 8, 9]])
Press <q> to quit, <Enter> to execute... output: array([[5, 6, 7], [6, 7, 8], [7, 8, 9]]) END OF DEMO Use <demo_name>.reset() if you want to rerun it. It uses IPython.demo. It's not especially pretty, but it's servicable. Code is at the end of this file: http://www.enthought.com/~rkern/cgi-bin/hgwebdir.cgi/kernmagic/file/c18f492e... -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On Wed, Aug 5, 2009 at 5:24 PM, Robert Kern<robert.kern@gmail.com> wrote:
And when you finish, send it our way. Operators are standing by to take your patch and your credit card number... :)
Something like this?
[...] # Robert, as usual, rocks.
It uses IPython.demo. It's not especially pretty, but it's servicable.
Yes, with Tom's recent demo improvements, this is precisely what I had in mind.
Code is at the end of this file:
http://www.enthought.com/~rkern/cgi-bin/hgwebdir.cgi/kernmagic/file/c18f492e...
Fantastic, many thanks. We can now properly track it: https://bugs.launchpad.net/ipython/+bug/409633 Hopefully once we land Brian's refactoring, we can start merging features again :) Now, that credit card number... f
participants (4)
-
Emmanuelle Gouillart -
Fernando Perez -
Pauli Virtanen -
Robert Kern