<br><br><div class="gmail_quote">On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord <span dir="ltr"><<a href="mailto:fuzzyman@voidspace.org.uk">fuzzyman@voidspace.org.uk</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
On 14/04/2010 01:25, Georg Brandl wrote:<br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
[snip...]<div class="im"><br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
A PEP might be necessary to make this a firm decision. What do you think<br>
about adopting epydoc reST markup for documenting the stdlib API?<br>
<br>
</blockquote>
> From me, +1.<br>
<br>
(Also for this reason: Many projects pull docstrings into their Sphinx docs<br>
via autodoc these days, and some also document inherited APIs. When these<br>
inherited APIs come from the stdlib, the markup is often confusing or not<br>
even valid reST.)<br>
<br>
</div></blockquote>
<br>
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.<br>
<br></blockquote><div>Agreed that a reST based standard would be very useful. <br><br>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. <a href="http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines">http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines</a> This is quickly becoming a standard for scientific projects (numpy, scipy, matplotlib, ipython etc). For an example see <a href="http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/">http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/</a>, click "source" for plain text version. Basic format is:<br>
<br>"""Summary line.<br><br>Parameters<br>------------<br>param1 : int<br> Description of param1. Can be multi-line.<br>param2: array<br> Description of param2.<br><br>Returns<br>-------<br>val1 : float<br>
<br>Example<br>-------<br><examples in doctest format><br>"""<br><br>There is also a very nice wiki doc editor with svn merging support (into the wiki automatic, patch generation for import into svn) here: <a href="http://docs.scipy.org/numpy/docs/">http://docs.scipy.org/numpy/docs/</a>. <br>
<br>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.<br><br>Best regards,<br>Ralf<br> <br></div></div>
<br>