[Numpy-discussion] Code samples in docstrings mistaken as doctests
Mon Jun 23 13:46:11 CDT 2008
On Mon, Jun 23, 2008 at 11:17 AM, Alan McIntyre <email@example.com> wrote:
> On Mon, Jun 23, 2008 at 2:02 PM, Fernando Perez <firstname.lastname@example.org> wrote:
>> There's also the option of marking them so doctest skips them via
>> #doctest: +SKIP
> 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:
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
Just some ideas...
More information about the Numpy-discussion