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

David Goodger goodger@users.sourceforge.net
Tue, 02 Apr 2002 19:43:25 -0500

• Previous message: [Python-Dev] PEP 287: reStructuredText Standard Docstring Format
• Next message: [Python-Dev] PEP 287: reStructuredText Standard Docstring Format
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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

• Previous message: [Python-Dev] PEP 287: reStructuredText Standard Docstring Format
• Next message: [Python-Dev] PEP 287: reStructuredText Standard Docstring Format
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]