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

[Pauli Virtanen]

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 
results.

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 
printout.

-- 
Pauli Virtanen