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

[Anne Archibald]

2008/6/23 Stéfan van der Walt <stefan at sun.ac.za>:
> 2008/6/24 Stéfan van der Walt <stefan at sun.ac.za>:
>> 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.
>
> Mike Hansen just explained to me that the Sage doctest system sets the
> random seed before executing each test.  If we address
>
> a) Random variables
> b) Plotting representations and
> c) Endianness
>
> we're probably halfway there.

I agree (though I have reservations about how they are to be
addressed). But in the current setting, "halfway there" is still a
problem - it seems to me we need, now and later, a way to deal with
generic examples that are not doctests. There may not be many of them,
and most may be dealt with by falling into categories a, b, and c
above, but it is important that we not make it difficult to write new
examples even if they can't readily be made into doctests. In
particular, we don't want some documentor saying "well, I'd like to
write an example, but I don't remember the arcane syntax to prevent
this failing a doctest, so I'm not going to bother."

Anne