[Python-Dev] Docutils/reStructuredText is ready to process PEPs

[David Goodger]

Python-developers,

Pursuant to PEP 287, one of the deliverables of the just-released
Docutils 0.2 (http://docutils.sf.net/) is a processing system for
reStructuredText-format PEPs as an alternative to the current PEP
processing.  Here are examples of new-style PEPs (processed to HTML,
with links to the source text as usual):

- http://docutils.sf.net/spec/pep-0287.html (latest)
- http://docutils.sf.net/spec/pep-0000.html (as a proof of concept
  because of its special processing)

Compare to the old-style PEPs:

- http://www.python.org/peps/pep-0287.html (update pending)
- http://www.python.org/peps/pep-0000.html

Existing old-style PEPs can coexist with reStructuredText PEPs
indefinitely.  What to do with new PEPs is a policy decision that
doesn't have to be made immediately.  PEP 287 puts forward a detailed
rationale for reStructuredText PEPs; especially see the "Questions &
Answers" section, items 4 through 7.

In earlier correspondence Guido critiqued some style issues (since
corrected) and said "I'm sure you can fix all these things with a
simple style sheet change, and then I'm all for allowing Docutils for
PEPs."  I'd appreciate more critiques/suggestions on PEP formatting
issues, no matter how small.  Especially, please point out any
HTML/stylesheet issues with the various browsers.

I hereby formally request permission to deploy Docutils for PEPs on
Python.org.  Here's a deployment plan for your consideration:

- Install the Docutils-modified version of Fredrik Lundh's
  nondist/peps/pep2html.py script into CVS, along with ancillary
  files.  The modified pep2html.py auto-detects old-style and
  new-style PEPs and processes accordingly.
  (http://docutils.sf.net/tools/pep2html.py)

- Install Docutils 0.2 on the server that does the PEP processing.  I
  don't think it's necessary to put Docutils into Python's CVS.

- Make up a README for the "peps" directory with instructions for
  installing Docutils and running the modified pep2html.py.

- Modify PEP 1 (PEP Purpose and Guidelines) and PEP 9 (Sample PEP
  Template) with the new formatting instructions.

- Make an announcement to the Python community.

- I will maintain the software, convert current meta-PEPs to the new
  format as desired, handle PEP conversion updates, and assist other
  PEP authors to convert their PEPs if they wish.

If this is acceptable, to begin I will need write access to CVS and
shell access to the Python.org server (however that works; please let
me know what I need to do).  Once I have the necessary access, I will
try to ensure a near-zero impact on the PythonLabs crew.

Feedback is most welcome.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/