[Doc-SIG] Python docs in reST?
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).
More information about the Doc-SIG