On Mon, 16 May 2005 10:24:27 +0100
Michael Hudson <[EMAIL PROTECTED]> wrote:
>
> Skip Montanaro <[EMAIL PROTECTED]> 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
_______________________________________________
Doc-SIG maillist - [email protected]
http://mail.python.org/mailman/listinfo/doc-sig
