[Python-Dev] status of development documentation

[Walter Dörwald]

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