On Jan 23, 2006, at 2:13 PM, Ian Bicking wrote:
Bob Ippolito wrote:
On Jan 23, 2006, at 1:21 PM, Kevin Dangoor wrote:
I'm planning to take a run through the tg code and update API docs
while I'm at it. I'm not enormously fond of epydoc, and I think
Fredrik Lundh's Pythondoc looks good:
http://effbot.org/zone/pythondoc.htm
Its default output is pretty readable and allows us to intelligently
annotate the code (much like epydoc does). It looks like it'll be
easy
to format things however we wish, and Fredrik is actively working on
it (as it is, I'm using a hacked version of epydoc, which no longer
seems to be maintained).
Though Pudge uses Kid templates, I'm not as keen on the output it
produces and the fact that it doesn't allow the same kinds of
annotations you can do with pythondoc. Something I *do* like about
Pudge and hacked into my epydoc is the links to colorized source.
Sometimes the source remains the best document, and having that a
click away is a bonus.
Well, Pudge is definitely a work in progress. I like the fact
that the docs are reStructuredText more than anything.. and I
think the docs for simple_json turned out pretty decently:
http://svn.red-bean.com/bob/simplejson/trunk/docs/index.html
The problem with Pudge is that you do need to hack it a bit in
order to do what you want, but commit bits are pretty easy to
come by.
Probably most of the TG developers already have commit, actually;
Ryans been giving *.lesscode access instead of just one-per-
repository.
I certainly like ReST, and I like Pudge's layout generally.
Certainly some layout things could use some work, but that's mostly
just a matter of spit-and-polish, nothing fundamental. Annotations
would be significantly harder. I've started creating actual HTML
links to link items to each other, but it's a little crude -- fully
annotated links would certainly be better. That said, doing post-
processing on the generated HTML does not seem so bad to me
(docutils people always seem to find this terrible, but it seems
fine to me), and not too hard either. That's just the difference
between, say, `turbogears.expose <module-turbogears.html#expose>`_
(which works now) and `turbogears.expose <turbogears.expose>`_
(which is I think is like the kind of links Fredrik is making).
Heck, we could try to create another pass that creates his markup,
and use his tools. I think he even suggested such stacking as a
design goal.
Hacking docutils isn't all that hard. In order to build the MochiKit
documentation, I wrote a small script (barely over 100 lines of
liberally spaced code) that uses publish_parts to:
1. Add two custom roles to docutils (mochidef for defining functions,
mochiref for referencing them)
2. Insert some custom includes in the HTML output (the new JavaScript-
generated TOC feature, custom CSS)
3. Walk a directory tree and create the docs.
The script is here:
http://svn.mochikit.com/mochikit/trunk/scripts/make_docs.py
Here is an example of the output:
http://mochikit.com/doc/html/MochiKit/DOM.html
What Pudge brings to the party is the ability to find the reST in
docstrings, discover the module layout, and nicely display the source
code in reference to the functions. Adding features like annotations
can be done relatively easily, because you don't even need to touch
Pudge code to add roles to docutils.
-bob
