[Doc-SIG] epydoc reST markup for stdlib docstrings
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
Also, the numpy docstring conventions also aren't valid reST and therefore
need preprocessing. (Making them reST isn't hard but requires even more
More information about the Doc-SIG