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

Thu, 1 Aug 2002 01:32:27 -0500

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