<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
On 14/04/2010 16:48, Ralf Gommers wrote:
<blockquote
cite="mid:k2pdde7764a1004140748ocff97420g7408929b2dcde49d@mail.gmail.com"
type="cite"><br>
<br>
<div class="gmail_quote">On Wed, Apr 14, 2010 at 10:23 PM, Georg
Brandl <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:g.brandl@gmx.net">g.brandl@gmx.net</a>></span> wrote:<br>
<blockquote class="gmail_quote"
style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; 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 moz-do-not-send="true"
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>
<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>
</font></div>
</div>
</blockquote>
I would say that reading docstrings in a terminal is the *main* use
case - but that is why I tend to value the vertical space highly and
personally prefer the less verbose way.<br>
<br>
Michael<br>
<br>
<br>
<blockquote
cite="mid:k2pdde7764a1004140748ocff97420g7408929b2dcde49d@mail.gmail.com"
type="cite">
<div class="gmail_quote">
<div><font color="#888888"><br>
Cheers,<br>
Ralf</font> </div>
</div>
<pre wrap="">
<fieldset class="mimeAttachmentHeader"></fieldset>
_______________________________________________
Doc-SIG maillist - <a class="moz-txt-link-abbreviated" href="mailto:Doc-SIG@python.org">Doc-SIG@python.org</a>
<a class="moz-txt-link-freetext" href="http://mail.python.org/mailman/listinfo/doc-sig">http://mail.python.org/mailman/listinfo/doc-sig</a>
</pre>
</blockquote>
<br>
<br>
<pre class="moz-signature" cols="72">--
<a class="moz-txt-link-freetext" href="http://www.ironpythoninaction.com/">http://www.ironpythoninaction.com/</a></pre>
</body>
</html>