[Numpy-discussion] Code samples in docstrings mistaken as doctests

Pauli Virtanen pav@iki...
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 <alan.mcintyre@gmail.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 
non-graphical backend.)

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 

Pauli Virtanen

More information about the Numpy-discussion mailing list