Re: epydoc reST markup for stdlib docstrings
Georg Brandl <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
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 _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig