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

[Guido van Rossum]

[Jeremy]
> To paraphrase Aristole, wisdom comes from choosing wisely in
> the particular situation.

I thought that wisdom came from experience, and experience from lack
of wisdom.  (Or is that common sense?  There's a lot of wisdom in
common sense.)

I believe that reStructuredText comes from a lot of experience: long
discussions about requirements in the doc-sig, and experience with
e.g. Zope's StructuredText (which definitely represents the "lack of
experience" position IMO).

I think that reStructuredText is a good format for marking up
docstrings; it's probably as good as it gets given the requirements (a
fairly elaborate feature set, yet more readable "in the raw" than
HTML).

But if you ask me "should we use this for the standard library" I
think I'll have to say no.  Python's library reference documentation
is written using LaTeX, like it or not, and it's not going to change
any time soon.  (*If* and *when* it changes, it's probably going to be
something XMLish.  But since XML is so more verbose than LaTeX, I'm
not sure there's much of a point to this, at least unless bitrot takes
the LaTeX toolchain away from us.)

Given this status quo, docstrings in the Python standard library
should not try to duplicate the library reference documentation;
instead, they should be no more than concise hints.  For such
docstrings, a markup language, even reStructuredText, is
inappropriate.

IOW, reStructuredText is not even an option for new standard library
modules.  I agree with Jeremy that the PEP needs to be clear and
explicit about this.

--Guido van Rossum (home page: http://www.python.org/~guido/)