[Python-Dev] Docutils/reStructuredText is ready to process PEPs
Wed, 31 Jul 2002 21:17:22 -0400
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)
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.
- 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 <email@example.com> 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/