[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

David Abrahams David Abrahams" <david.abrahams@rcn.com
Fri, 5 Apr 2002 23:26:45 -0500

From: "Guido van Rossum" <guido@python.org>
> Alas, I find both the input and the output of the reST-ized version
> worse than the original.  The original takes up much less vertical
> space, which (given the goal of being a relatively terse hint rather
> than formal reference docs) counts for more than bullets, boxes and
> color.  The situation would be different if the goal was to replace
> the reference docs, but since it isn't, I think the informal markup is
> just fine.

I have to agree with Guido, for the same reasons. I wonder if it's the
input markup that's "wrong", or if it just needs a better backend for
generating HTML from the markup.

Incidentally, I'm really excited about reST. I've been looking for a
tolerable markup for C++ comments, and reST looks like it might fit the

Other musings:

A reST-based Wiki would give people an easy way to see how they like the

Is it just me, or are docstrings less-convenient than comments? Any
thought given to reST-processing a module's comments?