Re: epydoc reST markup for stdlib docstrings
Michael Foord <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
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, Michael > OTOH, the specifics don't matter as much as just picking one for the stdlib. > > -Barry > > -- http://www.ironpythoninaction.com/ _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig