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

[Fernando Perez]

On Mon, Jun 23, 2008 at 11:17 AM, Alan McIntyre <alan.mcintyre at gmail.com> wrote:
> On Mon, Jun 23, 2008 at 2:02 PM, Fernando Perez <fperez.net at gmail.com> wrote:
>> There's also the option of marking them so doctest skips them via
>>
>> #doctest: +SKIP
>>
>> http://docs.python.org/lib/doctest-options.html
>
> For short examples, that seems like a good option, but it seems like
> you have to have that comment on every line that you want skipped.
> There are some long examples (like the one in
> lib/function_base.py:bartlett) that (to me) would look pretty ugly
> having that comment tacked on to every line.

Ugh.  Definitely too ugly if it has to go in every line.  From reading
the docs I interpreted it as affecting the whole example, which would
be far more sensible...

> Either way is fine with me in the end, though, so long as it doesn't
> produce test failures. :)

Yes, but we also want to make these really easy for users to cleanly
paste in with minimal effort.  I wonder if a decorator could be
applied to those functions so that nose would then skip the doctests:

@skip_doctest
def foo()....

but the nose doctest plugin isn't exactly a model of modularity, so
I'm not sure you want to go down that particular road...

The no-prompts option seems to be the cleanest right now.  You may
want then to instead just use a reST block for those, so that sphinx
eventually renders them nicely at least as blocks:

    Plot the window and its frequency response::    ### <<< Added
double colon here

      from numpy import clip, log10, array, bartlett   ### <<< Extra
indent so this is a reST block
      from scipy.fftpack import fft

etc...

Just some ideas...


Cheers,

f