[Python-Dev] PEP 287: reStructuredText Standard Docstring Format (original) (raw)

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 bill.

Other musings:

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

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

-Dave