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

[Stéfan van der Walt]

2008/6/23 Michael McNeil Forbes <mforbes at physics.ubc.ca>:
> One can usually do #3 -> #1 or #2 by just leave bare assignments
> without printing a result (the user can always execute them and look
> at the result if they want).
>
>  >>> r = np.random.rand(3,2,4)
>
> which is cleaner than adding any flags...

Purposefully reducing the clarity of an example to satisfy some tool
is not an option.  We might be able to work around this specific case,
but there will be others.

It should be fairly easy to execute the example code, just to make
sure it runs.  We can always work out a scheme to test its validity
later.

One route is to use the same docstring scraper we use for the
reference guide, to extract all tests.  We can then choose a markup
which identifies tests with unpredictable results, and refrain from
executing them.  In some instances, we can even infer which tests to
ignore, e.g. the '>>> plt.' example Pauli mentioned.

Regards
Stéfan