Mon, 23 Jun 2008 10:03:28 +0200, Stéfan van der Walt wrote: > 2008/6/23 Alan McIntyre <[EMAIL PROTECTED]>: >> 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 _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
