[Doc-SIG] Python docs in reST?

[Michael Foord]

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.
>
>Thoughts?
>
>  
>
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).

Regards,

Fuzzy
http://www.voidspace.org.uk/python

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