[Numpy-discussion] something wrong with docs?

[Fernando Perez]

On Tue, Sep 22, 2009 at 7:31 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> Later in this thread, Fernando, you make a good case - scalability - for
> this, which, as someone who's been using only >>>, raises a number of
> questions in my mind: 0) this isn't applicable to docstrings, only to
> numpy-docs (i.e., the .rst files),

Yes, and to me this naturally divides things: examples in docstrings
should be compact enough that they fit comfortably in a >>> style.  If
they need an entire page of code, they probably should be in the main
docs but not in the docstring.  So I like very much the sphinx doctest
code blocks for longer examples interspersed with text, and the >>>
style for short ones that are a good fit for a docstring.

 correct; 1) assuming the answer is "yes,"
> is there a "standard" for these ala the docstring standard, or some other
> extant way to promulgate and "strengthen" your "suggestion" (after proper
> community vetting, of course);

I'm not sure what you mean here, sorry.  I simply don't understand
what you are looking to "strengthen" or what standard there could be:
this is regular code that goes into reST blocks.  Sorry if I missed
your point...

2) for those of us new to this approach, is
> there a "standard example" somewhere we can easily reference?

Yes, the sphinx docs have a page about the directive, including a brief example:

http://sphinx.pocoo.org/ext/doctest.html

Cheers,

f