[Numpy-discussion] Plot directive in numpy docs

Scott Sinclair scott.sinclair.za@gmail....
Sat Dec 13 06:14:23 CST 2008


> 2008/12/12 Pauli Virtanen <pav@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


More information about the Numpy-discussion mailing list