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.
--
Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org
