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

[Jeremy Hylton]

One more response.  I just chatted with Guido, and he helped me see a
different purpose for the PEP.  It sounds like reStructuredText (reST)
is intended for people who do want to write all the documentation in
docstrings.  If that's the goal, then it's fine if the doc-sig wants
to settle on reST as the answer for those people.

I wouldn't object to seeing this PEP approved as an informational PEP
that described reST as an optional format for docstrings.  (I'm
assuming that there is consensus in the doc-sig that reST is the right
solution.)  As such, the PEP shouldn't be trying to convince people to
use reST so much as it should describe the reST format.  If the PEP is
just going to be an advocacy document, there's not much point to a
PEP.  Or maybe the PEP could just say "reST is documented elsewhere.
The doc-sig has agreed on this as the standard
all-things-to-all-people format for the following reasons: ..."

As an optional format, I think it would be helpful to explicitly note
that it will not be used for the Python standard library.  We've
already got pretty good documentation for the library in LaTex, and I
can't think of any reason to move all that text into the source code
of the modules.

Jeremy