[Doc-SIG] epydoc reST markup for stdlib docstrings
ralf.gommers at googlemail.com
Wed Apr 14 02:26:25 CEST 2010
On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord <fuzzyman at voidspace.org.uk>wrote:
> On 14/04/2010 01:25, Georg Brandl wrote:
>> A PEP might be necessary to make this a firm decision. What do you think
>>> about adopting epydoc reST markup for documenting the stdlib API?
>> > From me, +1.
>> (Also for this reason: Many projects pull docstrings into their Sphinx
>> via autodoc these days, and some also document inherited APIs. When these
>> inherited APIs come from the stdlib, the markup is often confusing or not
>> even valid reST.)
> Definite +1 from me on adopting reST in docstrings as a standard. I haven't
> looked at the Epydoc convention for parameters (etc) well enough to have an
> opinion on that.
> Agreed that a reST based standard would be very useful.
One point that is important to me (and many scientific users) is how the
docstring looks in a terminal. Numpy has been developing a standard for
docstrings and writing docs that both looks good in plain text and in docs
rendered with Sphinx.
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This is quickly
becoming a standard for scientific projects (numpy, scipy, matplotlib,
ipython etc). For an example see
"source" for plain text version. Basic format is:
param1 : int
Description of param1. Can be multi-line.
Description of param2.
val1 : float
<examples in doctest format>
There is also a very nice wiki doc editor with svn merging support (into the
wiki automatic, patch generation for import into svn) here:
As far as I can tell the epydoc standard is not nearly as readable as the
numpy standard in plain text, so please consider the latter or something
similar for adoption.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Doc-SIG