[Numpy-discussion] Doctest items

[Stéfan van der Walt]

2008/7/2 Ryan May <rmay31 at gmail.com>:
>> To be clear, these aren't tests of the numpy code. The tests would be
>> to make sure the examples still run.
>>
> Right.  I just don't think effort should be put into making examples
> using matplotlib run as doctests.  If the behavior is important, numpy
> should have a standalone test for it.

Still, I'd like to see consistent markup for code snippets.
Currently, those are indicated by '>>>'.  First and foremost,
docstrings (in NumPy, with its test suite) are not tests, but serve as
documentation.  Running them is simply a way of verifying that we did
not make mistakes in the examples.

Matplotlib docstrings:

Currently, the plotting docstrings have not been written as valid
doctests, because I didn't want them riddled with:

[<matplotlib.lines.Line2D object at 0x33f60d0>]

How about a slight modification to Fernando's idea: a dummy function that

a) Does nothing if matplotlib is not installed
b) Otherwise passes through calls to matplotlib, after setting the
backend to /dev/null.  Any results (lines, figures, etc.) are
suppressed.

This limits us to very simple graphical examples, but I'm ok with
that.  If you really need to get hold of the figure, for example, you
could always use `figure(); f = gcf()` instead of `f = figure()`.

Pasting code:

I recommend using the %cpaste magic in IPython.  It has been updated
to support line-spanning examples.

Alan:  The latest versions of the docstrings are on the wiki, and
there are a number of examples using matplotlib.  These are always
listed last in the examples section, so that they can be easily
ignored by terminal-only users.

We'll definitely merge the wiki docstrings to into the source tree
before the conference.  I've been at a workshop this past week, but on
Monday I'll proceed full-steam again.

Regards
Stéfan