[Python-Dev] status of development documentation (original) (raw)

Walter Dörwald walter at livinglogic.de
Fri Dec 23 02:11:55 CET 2005

Phillip J. Eby wrote:

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.

OK, I didn't realize that.

I guess the only thing compatible with LaTeX is LaTeX.

I'd really like to see a version of Fred's XML converter that works for the current Python documentation.

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/Pythonxmlns.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:.

This sound like it should be possible.

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.

More the other way around.

For that matter, you could take a reST document and simply transform it to XML for use with the rest of your toolset.

That's the way I'd like to use docutils: Write docstring in reST and transform them via XML tools.

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.

If we had a way to losslessly convert Python-LaTeX to XML tools for both system could live side by side.

Bye, Walter Dörwald

More information about the Python-Dev mailing list