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

[David Goodger]

Guido van Rossum wrote:
Guido van Rossum wrote:
> Good PEP, David!

Thanks!  I'll take the generally positive tone of your reply as a good
sign.

> What's the next step?

Mark the PEP as "Accepted"?  But first, I'd like to address any issues
that may be raised.  I'd like to give people a few days at least to
respond.  Does a lack of responses mean that there *are* no issues?

I came here for a good argument!

Seriously though, just accepting the PEP would be great progress.

> Should the processing code be incorporated in the standard library?

It's not ready for that yet.  Here's a summary of the state of the
code:

- The project is split in two at present: the parser and everything
  else (the DPS proper).  They are to be merged & renamed to
  "Docutils".  This will remove some artificial complexity, reduce
  some redundancy especially with the test code, and make the whole
  thing much easier to install.

- The parser is functionally complete for standalone documents, and
  works quite well (passes all 300 unit tests).  However,

  - The code needs some serious refactoring in places.

  - The internal documentation needs to be completed.

- The non-parser part (current DPS) is still in its infancy.  It's
  currently only able to process standalone documents into simple HTML.

- The docstring extraction & processing part of Docutils (what I call
  the "Python source reader" component) is nowhere near ready.
  Implementing the Python roles for "interpreted text" (links based on
  namespace context) will need a significant effort.  But that has
  more to do with PEP 258.

  BTW, expect PEP revisions soon, Barry!

- There's no support for PEP processing yet.  Assuming that this part
  of the PEP is accepted,

  - The PEP strategy for section headers must first be decided (as-is
    plus reStructuredText in the indented body text, or replace with
    underline syntax and drop the indents, or allow both).

  - The parser needs support for PEP-specific constructs (RFC 2822
    headers; recognize "PEP \d+" and "RFC[- ]?\d+" as links; Q&A).

  - pep2html.py will need some work.  It would become a front-end to
    a "PEP reader" component.

I think the Docutils code should continue to be developed separately
from the stdlib, until it is worthy.  It may or may not be ready in
time for 2.3, depending on the usual factors: my time, getting more
interested developers on board, etc.  The PEP processing part could be
installed before the full docstring processing part is ready; that
should be doable for 2.3.

> Should we start converting the standard library docs to
> reStructuredText?

I assume you mean "docstrings"?  Oherwise Fred may take exception, at
least until LaTeX support is in place.  ;-)

There's no rush to convert library docstrings.  There won't be a
benefit for a while, but there's no danger either.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net