<br><br><div class="gmail_quote">On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <span dir="ltr"><<a href="mailto:g.brandl@gmx.net">g.brandl@gmx.net</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;">
Am 14.04.2010 14:07, schrieb Barry Warsaw:<br>
<div class="im">> On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:<br>
><br>
>>Barry Warsaw wrote:<br>
>>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:<br>
>>><br>
>>>> Definite +1 from me on adopting reST in docstrings as a standard. I<br>
>>>> haven't looked at the Epydoc convention for parameters (etc) well enough<br>
>>>> to have an opinion on that.<br>
>>><br>
>>> The thing I like about them is that the rules are very simple, and once<br>
>>> learned are easy to remember.<br>
>><br>
>>Did you look at the NumPy guidelines Ralf posted?:<br>
>><a href="http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines" target="_blank">http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines</a><br>
>><br>
>>Those look very clean to me, and fairly similar to what we already do in<br>
>>the ReST docs.<br>
>><br>
>>Because epydoc works with tags rather than sections, it looks a lot<br>
>>"noisier" to me when reading the plain text version.<br>
><br>
> And I'm not keen on the sections since I think they consume too much vertical<br>
> whitespace. And I like the tags of epydoc format on the left side for their<br>
> regularity.<br>
<br>
</div>Also, the numpy docstring conventions also aren't valid reST and therefore<br>
need preprocessing. (Making them reST isn't hard but requires even more<br>
vertical space.)<br>
<font color="#888888"></font><br></blockquote><div><font color="#888888">The preprocessing should not be an issue, especially since the code for
that already exists and is heavily used.<br><br>The vertical whitespace
vs tags is a taste issue, I agree, from a developer perspective. From a
user perspective however, the numpy standard is clearly more readable in
a terminal. That's why it looks the way it does. And reading docstrings
in a terminal is not a fringe use case by the way.<br>
<br>Cheers,<br>Ralf</font> </div></div>