[Doc-SIG] epydoc reST markup for stdlib docstrings

Michael Foord fuzzyman at voidspace.org.uk
Wed Apr 14 17:37:28 CEST 2010

On 14/04/2010 16:07, Barry Warsaw wrote:
> 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.  Everyone's got a different opinion, and the only one that matters
> is the BDFL's. :)

Well, perhaps move this discussion to python-dev with the intent of 
creating a PEP and asking for BDFL pronouncement? The two contenders 
seem to be numpy format and epydoc format. We seem to have a consensus 
that adopting a standard for the standard library is a good idea.

Once we have settled on a basic format we can thrash out all the 
specifics in the PEP.

All the best,

> OTOH, the specifics don't matter as much as just picking one for the stdlib.
> -Barry


More information about the Doc-SIG mailing list