> 2008/12/12 Pauli Virtanen <p...@iki.fi>: > Fri, 12 Dec 2008 14:20:50 +0100, Gael Varoquaux wrote: >> What is the guideline on using the plot directive in the numpy docs? > > 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. > > ** 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 prefer this approach, with the examples section assumed to be wrapped in a plot directive, rather than having the markup in the docstring itself. I'm not clear on what you mean by earlier examples. Do you mean earlier examples in the same docstring, or earlier examples in other docstrings? It makes most sense to me if each docstring has self contained examples and doesn't rely on anything defined elsewhere (except the obvious 'import numpy as np'). > 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. However this is resolved, I wouldn't like to see any doctest markup in the finished documentation, whether this is viewed in the terminal, as html or as a pdf. Cheers, Scott _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
