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

[Emmanuelle Gouillart]

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