[Numpy-discussion] something wrong with docs?
Tue Sep 22 23:29:11 CDT 2009
On Tue, Sep 22, 2009 at 7:31 PM, David Goldsmith
> 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
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:
More information about the NumPy-Discussion