[Doc-SIG] epydoc reST markup for stdlib docstrings

[Ralf Gommers]

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:
>
>> [snip...]
>>
>>  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
>> docs
>> 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
http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/, click
"source" for plain text version. Basic format is:

"""Summary line.

Parameters
------------
param1 : int
    Description of param1. Can be multi-line.
param2: array
   Description of param2.

Returns
-------
val1 : float

Example
-------
<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:
http://docs.scipy.org/numpy/docs/.

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.

Best regards,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/2a7528b1/attachment-0001.html>