On 14/04/2010 16:48, Ralf Gommers wrote:
On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.bra...@gmx.net
<mailto:g.bra...@gmx.net>> wrote:
Am 14.04.2010 14:07, schrieb Barry Warsaw:
> On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
>
>>Barry Warsaw wrote:
>>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
>>>
>>>> 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.
>>>
>>> The thing I like about them is that the rules are very simple,
and once
>>> learned are easy to remember.
>>
>>Did you look at the NumPy guidelines Ralf posted?:
>>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
>>
>>Those look very clean to me, and fairly similar to what we
already do in
>>the ReST docs.
>>
>>Because epydoc works with tags rather than sections, it looks a lot
>>"noisier" to me when reading the plain text version.
>
> And I'm not keen on the sections since I think they consume too
much vertical
> whitespace. And I like the tags of epydoc format on the left
side for their
> regularity.
Also, the numpy docstring conventions also aren't valid reST and
therefore
need preprocessing. (Making them reST isn't hard but requires
even more
vertical space.)
The preprocessing should not be an issue, especially since the code
for that already exists and is heavily used.
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.
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.
Michael
Cheers,
Ralf
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
--
http://www.ironpythoninaction.com/
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
