[Doc-SIG] epydoc reST markup for stdlib docstrings

[Georg Brandl]

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?:
>>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
>>
>>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.)

Georg