[Doc-SIG] Python docs in reST?

Michael Foord mike at pcblokes.com
Mon May 16 10:05:05 CEST 2005

Skip Montanaro wrote:

>A thread on c.l.py ("Python Documentation (should be better?)") got me to
>thinking about options for improving/restructuring the online documentation.
>That led me to thinking about converting the current docs to reST.  A scan
>of the last year's worth of list archives didn't yield any obvious
>discussion on the topic, but I find it hard to believe the topic hasn't been
>discussed in the past.  Pointers to past threads cheerfully accepted.
>It seems to me that converting to reST has a couple obvious benefits:
>    * dump latex2html
>    * better potential HTML generation options (like HTML w/ an integrated
>      annotation capability)
>    * possibly enlarge pool of documentation contributors
>Fred wrote some Latex->ESIS->SGML tools that look like they might possibly
>be redirected to the more-or-less one-time task of converting to reST.
As it stands the docutils tools are some way off being able to generate 
Python documentation. They are not yet targeted at multipage documents - 
this includes the navigation links and multi page contents/indexes.

I believe it is a long term goal (in which case Latex -> reST would be a 
worthy tool) - but not yet possible.

You can generate HTML fragments from reST and insert them into 
templates. This is the approach rest2web__ uses. I'm going to see if I 
can evolve rest2web to address some of the issues above for my own 
needs. Eventually a solution within docutils will evolve (hopefully - if 
I *can* contribute then I will).



__ http://www.voidspace.org.uk/python/rest2web

More information about the Doc-SIG mailing list