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

Jeremy Hylton jeremy@zope.com
Wed, 3 Apr 2002 13:58:36 -0500

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