[Numpy-discussion] Proposal for matrix_rank function in numpy

[Fernando Perez]

On Fri, Dec 18, 2009 at 8:10 PM, Robert Kern <robert.kern at gmail.com> wrote:
> My policy and rationale, which I believe is reflected in the docstring
> standard, is that examples in the docstrings should put pedagogical
> concerns above all others. In my experience, a properly robust doctest
> sacrifices the readability, clarity, and terseness of a good example.
> Thus, not all examples run as doctests, so docstrings are not added to
> numpy's test suite. For example, for floating point functions, one
> should use allclose(), etc. to test the results against the gold
> standard.

I think we mostly agree, up to a point: I also emphasized pedagogical
value, but I think it would be better in the long run if we could also
run all examples as part of the test suite.  This would act as a
protection against examples going stale due to changes in the
underlying code.  A false example is worse than no example at all.

I wonder if this couldn't be addressed by simply having a suitable set
of printing options wrapped up in a utility that doctests could all
use (4 digits only, setting certain flags, linewidth, etc).  This
could help with most of the problems with robustness and maintenance,
while allowing us to ensure that we can always guarantee that examples
actually do work.  Just a thought.

Cheers,

f