[Doc-SIG] epydoc reST markup for stdlib docstrings

Georg Brandl g.brandl at gmx.net
Wed Apr 14 16:23:59 CEST 2010

Am 14.04.2010 14:07, schrieb Barry Warsaw:
> On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
>>Barry Warsaw wrote:
>>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
>>>> 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.
>>> The thing I like about them is that the rules are very simple, and once
>>> learned are easy to remember.
>>Did you look at the NumPy guidelines Ralf posted?:
>>Those look very clean to me, and fairly similar to what we already do in
>>the ReST docs.
>>Because epydoc works with tags rather than sections, it looks a lot
>>"noisier" to me when reading the plain text version.
> And I'm not keen on the sections since I think they consume too much vertical
> whitespace.  And I like the tags of epydoc format on the left side for their
> regularity.

Also, the numpy docstring conventions also aren't valid reST and therefore
need preprocessing.  (Making them reST isn't hard but requires even more
vertical space.)


More information about the Doc-SIG mailing list