<br><br><div class="gmail_quote">On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <span dir="ltr">&lt;<a href="mailto:g.brandl@gmx.net">g.brandl@gmx.net</a>&gt;</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">&gt; On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:<br>
&gt;<br>
&gt;&gt;Barry Warsaw wrote:<br>
&gt;&gt;&gt; On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt;&gt; Definite +1 from me on adopting reST in docstrings as a standard. I<br>
&gt;&gt;&gt;&gt; haven&#39;t looked at the Epydoc convention for parameters (etc) well enough<br>
&gt;&gt;&gt;&gt; to have an opinion on that.<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; The thing I like about them is that the rules are very simple, and once<br>
&gt;&gt;&gt; learned are easy to remember.<br>
&gt;&gt;<br>
&gt;&gt;Did you look at the NumPy guidelines Ralf posted?:<br>
&gt;&gt;<a href="http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines" target="_blank">http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines</a><br>
&gt;&gt;<br>
&gt;&gt;Those look very clean to me, and fairly similar to what we already do in<br>
&gt;&gt;the ReST docs.<br>
&gt;&gt;<br>
&gt;&gt;Because epydoc works with tags rather than sections, it looks a lot<br>
&gt;&gt;&quot;noisier&quot; to me when reading the plain text version.<br>
&gt;<br>
&gt; And I&#39;m not keen on the sections since I think they consume too much vertical<br>
&gt; whitespace.  And I like the tags of epydoc format on the left side for their<br>
&gt; regularity.<br>
<br>
</div>Also, the numpy docstring conventions also aren&#39;t valid reST and therefore<br>
need preprocessing.  (Making them reST isn&#39;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&#39;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>