[Doc-SIG] Python docs in reST?

[Simon Burton]

On Mon, 16 May 2005 10:24:27 +0100
Michael Hudson <mwh at python.net> wrote:

> 
> Skip Montanaro <skip at pobox.com> writes:
> 
> > 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.
> 
> I thought it had too, but maybe only on python-list.
> 
> I'm not so sure it would make much difference, but maybe that's just
> my cynicism.
> 
> > It seems to me that converting to reST has a couple obvious benefits:
> >
> >     * dump latex2html
> 
> It works most of the time these days!
...

I should chime in here with another viewpoint. I do a lot of scientific/engineering python,
and have been using python's latex2html system for one good reason: we need math
expressions in the docs.

Originally I cooked up a script to rip docstrings, introspect function signatures, and write
the latex source out for the API docs. It quickly got out of hand: maybe because my
little script was too much of a hack, or maybe because the latex2html system does
not really lend itself well to the "three pane"-navigatable documentation style, especially
for deeply nested packages. Perhaps this could be improved with some more
latex macros; I don't know (latex scares the willies out of me).

Where I work now, they recently moved to python from a proprietary system. Mostly
I think everyone is enjoying the change, but my boss is shocked at the lack of
a "standard" python documentation system, and that the python docs are maintained
separately, by hand.

We looked at epydoc. I've had one (lame) attempt at integrating latex-math, no luck so far.
Now the boss is willing to pay a bounty for this feature, though I think we need
someone local (to Canberra, Australia).

Simon.


-- 
Simon Burton, B.Sc.
Licensed PO Box 8066
ANU Canberra 2601
Australia
Ph. 61 02 6249 6940
http://arrowtheory.com