[Python-Dev] status of development documentation

[Walter Dörwald]

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 
http://www.livinglogic.de/Python/xist/xsc/index_module.py (for 
docstrings) or at 
http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/Python/xist/HOWTO.xml?rev=2.110&content-type=text/vnd.viewcvs-markup 
for doc files. Possible output is:

* HTML: http://www.livinglogic.de/Python/xist/Howto.html

* Plain text (by piping a special HTML output through w3m): 
http://www.livinglogic.de/Python/xist/Howto.txt. It might probably be 
possible to extend this, so that the output is reST.

* XSL-FO: http://www.livinglogic.de/Python/xist/Howto.fo

* PDF (generated with FOP): http://www.livinglogic.de/Python/xist/Howto.pdf

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?

Bye,
    Walter Dörwald