On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord <fuzzy...@voidspace.org.uk>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 - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
