[Doc-SIG] epydoc reST markup for stdlib docstrings

[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.  Everyone's got a different opinion, and the only one that matters
is the BDFL's. :)

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

-Barry

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/6c290f00/attachment.pgp>