[Python-Dev] status of development documentation

[Phillip J. Eby]

At 10:27 AM 12/22/2005 +0100, Walter Dörwald wrote:
>Phillip J. Eby wrote:
>
> > [...]
> >
> > If someone has examples of actual "Pythondoc" markup that don't translate
> > to reST, I'd be really interested in seeing them, just for my own
> > education.  Of course, I'd also be curious how common such constructs are.
>
>I'm using XML markup for our packages. Examples can be found at
>[snip]

By "Pythondoc", I mean the LaTeX-based markup system being used for the 
official Python documentation, not arbitrary methods of documentation for 
Python code.


>The source is definitely wordier than reST, but adding new markup is
>trivial. Take a look at
>http://www.livinglogic.de/Python/xist/Download.html and at the source at
>http://www.livinglogic.de/Python/xist/Download.htmlxsc. The download
>element automatically determines the size of the package. Source can be
>found here
>http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/WWW-Python/site/Python_xmlns.py?rev=1.43&content-type=text/vnd.viewcvs-markup
>(search for "class download"). Would something like this be possible
>with reST?

The docutils toolchain converts reST input into a DOM, and allows arbitrary 
transformation phases to be added to processing before conversion to 
output.  This includes processing of "directives", e.g. commands like:

.. include:: filename

And of interpreted text "roles",  e.g. `Foobar`:class:.

It is not, however, a general XML transformation toolkit, if that's what 
you're asking.  However, if you wanted to be able to use XML input as part 
of a docutils DOM, you could certainly do that.  For that matter, you could 
take a reST document and simply transform it to XML for use with the rest 
of your toolset.

But this isn't particularly relevant to the discussion about *Python's* 
documentation, and I'm not even advocating that Python switch, let alone 
arbitrary other projects.