On Fri, Dec 18, 2009 at 8:10 PM, Robert Kern <robert.kern@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