Re: epydoc reST markup for stdlib docstrings
Ralf Gommers <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord <[email protected]>wrote: > On 14/04/2010 01:25, Georg Brandl wrote: > >> [snip...] >> >> A PEP might be necessary to make this a firm decision. What do you think >>> about adopting epydoc reST markup for documenting the stdlib API? >>> >>> >> > From me, +1. >> >> (Also for this reason: Many projects pull docstrings into their Sphinx >> docs >> via autodoc these days, and some also document inherited APIs. When these >> inherited APIs come from the stdlib, the markup is often confusing or not >> even valid reST.) >> >> > > 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. > > Agreed that a reST based standard would be very useful. One point that is important to me (and many scientific users) is how the docstring looks in a terminal. Numpy has been developing a standard for docstrings and writing docs that both looks good in plain text and in docs rendered with Sphinx. http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This is quickly becoming a standard for scientific projects (numpy, scipy, matplotlib, ipython etc). For an example see http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/, click "source" for plain text version. Basic format is: """Summary line. Parameters ------------ param1 : int Description of param1. Can be multi-line. param2: array Description of param2. Returns ------- val1 : float Example ------- <examples in doctest format> """ There is also a very nice wiki doc editor with svn merging support (into the wiki automatic, patch generation for import into svn) here: http://docs.scipy.org/numpy/docs/. As far as I can tell the epydoc standard is not nearly as readable as the numpy standard in plain text, so please consider the latter or something similar for adoption. Best regards, Ralf _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig