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

[Michael McNeil Forbes]

> On Mon, Jun 23, 2008 at 4:51 PM, Robert Kern  
> <robert.kern@gmail.com> wrote:
>>>>>> random_array = np.random.rand(3,4)
>>>>>> random_array.shape
>>> (3,4)
>>>>>> random_array.max() < 1
>>> True
>>>>>> random_array.min() > 0
>>> True
>>
>> Yes, this makes it doctestable, but you've destroyed the exampleness.
>> It should be policy *not* to do this.

Well perhaps... but do you think that

rand(d0, d1, ..., dn) -> random values

is more exampley than

 >>> r = np.random.rand(3,2,4)
 >>> r.shape
(3,2,4)

?

On 23 Jun 2008, at 2:31 PM, Alan McIntyre wrote:
> So it seems we have:
>  1. Example code that is doctestable
>  2. Example code that probably can't ever be doctestable (random
> number stuff, etc.), but is still executable
>  3. Schematic examples that aren't executable
>
> Personally, I'm in favor of filling out examples of type #3 to make
> them at least #2, but maybe that's not always practical.  I don't
> think #3 should ever have ">>>" prompts, so it shouldn't ever be
> picked up by doctest.
>
> I suppose I could go for a decorator option to flag #2. If we execute
> them, but not look at the results, then at least we find out about
> examples that are broken enough to raise exceptions.

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...

Michael.