
I would very much like to see reStructuredText, or some minor variation on it, move forward as a "standard" for doc-strings very soon. I have long lamented not having a prescribed format *and* an associated processing tool suite included in the standard library. Even if the format isn't perfect (I think it looks very good), it is time to pick a reasonable candidate and go. SciPy does not yet have a standard doc-string format. The .3 release of SciPy (we're at .2alpha) will primarily be a documentation/testing effort. I'd like to use the chosen standard so that we can auto-generate the reference manual without setting up some complex third party tools. The user documentation for SciPy may still end up in TeX (which is very hard for me to swallow) or Word (I know, I know) because of their power, but doc-strings need something simpler. If XML or something like that is chosen, we'd probably use it, but I'd be less excited because it doesn't read as well in plain text form. Also, it will be much harder to get the scientists that contribute modules to conform to this. I watched the doc-sig for many months a when SciPy was started, and there was a lot of discussion on the multitude of different choices. It seemed like 50% wanted a dirt simple mark up like Ka-Ping suggests, and 50% wanted TeX or XML for maximum power as Eric R. suggests. You can't satisfy both camps, but David seems to have balanced most of the issues very well. Looking at David's marked-up PEPs, they read very nicely as plain text. I'm fairly confident that, with these as an example and without reading the specification, I can write my own marked up document or doc-string with little effort. Diving into the longer spec is only needed if you want fancy stuff. There are no doubt millions of choices for marking up doc-strings. David's is quite reasonable, solves many problems with StructureText, *has a champion*, and looks to have a fairly good start on a tool suite. If another choice is as well balanced, *has a champion*, and has a prayer of having tools ready in the standard library soon, then lets consider it. Otherwise, the argument over the perfect markup choice has been kicked around enough over the last several years. Let's just tweak this one. I wish for less vertical white space and a simpler heading markup too, but, not so much that I'm willing to think through all this as thoroughly as David has. I no longer wish for a "perfect" markup, just a standard one -- and soon. On a related note, distutils is (far) less than perfect (sorry Greg), and I have cursed it on many occasions. However, it works, solves a huge problem, and (with modifications) made building the 130,000 or so lines of Python/C/Fortran code that is SciPy tractable in a platform independent way. Standardizing on reStructuredText will have similar impact. my 0.02, eric
-----Original Message----- From: python-dev-admin@python.org [mailto:python-dev-admin@python.org] On Behalf Of David Goodger Sent: Wednesday, July 31, 2002 8:17 PM To: python-dev@python.org Subject: [Python-Dev] Docutils/reStructuredText is ready to process PEPs
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/
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev