[Doc-SIG] epydoc reST markup for stdlib docstrings

Ralf Gommers ralf.gommers at googlemail.com
Wed Apr 14 17:13:15 CEST 2010

On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord
<fuzzyman at voidspace.org.uk>wrote:

>  On 14/04/2010 16:48, Ralf Gommers wrote:
> 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.

You're a core developer (I think). But for the *average* user, do you really
think tags are fine? Earlier in this thread there was a mention of people
that love to read XML. I'm exaggerating a bit of course, but this is
similar. Whitespace beats tags for readability.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/63ea33d3/attachment.html>

More information about the Doc-SIG mailing list