[Numpy-discussion] Code samples in docstrings mistaken as doctests
Mon Jun 23 14:57:08 CDT 2008
Mon, 23 Jun 2008 10:03:28 +0200, Stéfan van der Walt wrote:
> 2008/6/23 Alan McIntyre <email@example.com>:
>> Some docstrings have examples of how to use the function that aren't
>> executable code (see numpy.core.defmatrix.bmat for an example) in their
>> current form. Should these examples have the ">>>" removed from them
>> to avoid them being picked up as doctests?
> The examples written for the random module warrants the same question.
> First and foremost, the docstrings are there to illustrate to users
> how to use the code; second, to serve as tests.
> Example codes should run, but I'm not sure whether they should always be
> valid doctests.
> In the `bmat` example, I would remove the '>>>' like you suggested.
"Schematic" code (such as that currently in numpy.bmat) that doesn't run
probably shouldn't be written with >>>, and for it the ReST block quote
syntax is also looks OK.
But I'm personally not in favor of a distinction between a "doctest" and
a "code sample", as the difference is not of interest to the main target
audience who reads the docstrings (or the reference documentation
generated based on them). As I see it, Numpy has a test architecture that
is separate from doctests, so that most of the bonus doctests gives us is
ensuring that all of our examples run without errors and produce expected
It's a bit unfortunate though that the doctest directives are as
obtrusive as they are and only apply to a single line. One problem that I
see now is quite annoying in the sample codes using matplotlib:
matplotlib functions tend to return some objects whose <repr> contains a
memory address, which causes the code to fit badly in a doctest. This can
be worked around (ELLIPSIS, assigning to a variable), but I don't see a
clean way. (I'm not so worried here about plot windows popping up as they
can be worked around by monkey-patching matplotlib.show and choosing a
Another point related to numpy are blank lines often appearing in array
printouts (the text <BLANKLINE> is not a pretty sight in documentation).
Also, NORMALIZE_WHITESPACE is useful for reducing the whitespace in array
More information about the Numpy-discussion