[Doc-SIG] Updates to Docutils

David Goodger goodger@users.sourceforge.net
Fri, 19 Jul 2002 23:33:53 -0400

Download the latest snapshot from:


The sandbox snapshot is also available:


Lots of changes in the last few weeks:

* Added support for configuration files.  Config files
  (/etc/docutils.conf, ./docutils.conf, ~/.docutils) override
  application defaults, and command-line options override all.
  Documentation is pending.

* Added "simple tables" to reStructuredText (spec and parser):

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

* Improved HTML output with many small changes.

* Added PEP processing support:

  - tools/pep.py: Front-end for processing reStructuredText PEPs.
  - tools/pep2html.py: Based on the existing script (in CVS at
    python/nondist/peps); processes old-style *and* reStructuredText
  - docutils/writers/pep_html.py: HTML Writer for
    PEPs (subclass of ``html4css1.Writer``).

* Updated the PEPs:

  - A "Roadmap to the Docstring PEPs" section was added to PEP 256:

  - PEP 258 has been reorganized and extensively updated:


  - PEP 287: updated, renamed to "reStructuredText Docstring Format"
    and converted to reStructuredText format (provisionally, pending
    PythonLabs OK).  Check out the processed PEP 287:


    I also converted PEP 0 as a proof of concept because of its
    special processing:


    Late breaking news: I just got a reply from Guido, in which he
    critiques some style issues, then says, "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 on
    PEP formatting issues, no matter how small.  Especially, please
    help with stylesheet issues with the various browsers, by
    comparing the reStructuredText PEPs above to the old-style


* Added Docutils-native XML output:

  - tools/docutils-xml.py: A front-end.
  - docutils/writers/docutils_xml.py: A Writer.

* Unicode & encodings are working.

I hope to release Docutils version 0.2 in a week or two,
incorporating Swedish and German language patches I've received and
*maybe* the "inline external targets" syntax in some form.  After
that, I plan to focus on Python autodocumentation: analyze Tony Ibbs'
PySource code and Doug Hellman's HappyDoc project, take the best ideas
and integrate them into Docutils 0.3.

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/