[Python-Dev] status of development documentation

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

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