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

[Alan McIntyre]

On Mon, Jun 23, 2008 at 3:57 PM, Pauli Virtanen <pav at iki.fi> wrote:
> "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.

I agree with you, Anne and Michael that ensuring that the
documentation examples run is important.   The more I think about it,
the more I'd rather have examples that are a bit verbose.  In the
particular example of bmat, as a new user, I'd really honestly rather
see those three cases fully coded:

>>> A=nd.arange(1,5).reshape(2,2)
>>> B= etc.
>>> F=bmat('A,B;C,D')
>>> F
matrix([[1,2,5,6],
etc.