Fri, 12 Dec 2008 14:20:50 +0100, Gael Varoquaux wrote: > What is the guideline on using the plot directive in the numpy docs? It > can make some examples much easier to understand, but on the other hand, > it can clutter the docstrings. In addition, I am not sure how our > documentation pipeline deals with it.
No guideline yet, I'd suggest not to use it in docstrings yet, before we are sure it works as we want it to work. It does not (and probably will not, due to security reasons) work in the wiki. But it already works in the built documentation. ** How it works now .. plot:: import matplotlib.pyplot as plt x = np.linspace(0, 2*pi, 200) plt.plot(x, np.sin(x)) plt.show() assuming "import numpy as np" is pre-defined in a Sphinx conf.py directive. The code can either be in doctest format or not, this is automatically detected. Each matplotlib figure gets a separate image, for examples see the Scipy Tutorial. The code is executed and images are automatically captured into files when the documentation is built. (No need to use eg. savefig.) The code inside the plot:: directive cannot, due to technical reasons, access any variables etc. used in preceding doctests. ** What to think about - Should docstrings be assumed by default to lie inside plot:: directive, unless a plot:: directive is explicitly used? This way the plot could use stuff defined in earlier examples. - Or, maybe only the examples section should assumed to be in a plot:: by default, if it contains doctests. I'd think this would be a good idea. This way, we could continue using the current docstring standard, and be able to generate figures from the examples that use matplotlib. - I don't think the plot:: directive itself adds much line noise to the docstrings, but maybe some differ. - Where to allow plots in docstrings. I'd guess only in the examples section. - Whether to use doctest notation inside plot:: or not. - Our security model should continue to be as previously: the person who checks in docstrings from the wiki to SVN checks that the doctests do not contain malicious code. - We have technical leeway to do many things, because Sphinx allows us to preprocess docstrings in any way we want before processing them. Also: There was the unresolved question about should the example codes be run when numpy.test() is run, and what to do with matplotlib code in this case. The main problem was that if the plot codes are picked up as doctests, then the matplotlib objects returned by pyplot functions cause unnecessary line noise. Definitely, any doctest markup should be avoided in the examples. So the options were either to implement some magic to skip offending doctest lines, or to not use doctest markup for plots. -- Pauli Virtanen _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
