Bob Ippolito wrote:
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
That's not hard at all. My understanding is that Frederik's markup
might allow nesting, and I don't think you can generally nest docutils
roles, right? Though in the cases where you might want to (which might
not be many) it could potentially be faked with combination roles.
Here's the source file he's using:
http://effbot.org/lib/zipfile.txt
But I think the @@ stuff gets converted to markup later, which might be
an easier place to intercept.
One thing that's interesting about his approach is that the links don't
need to understand what their targets are -- i.e., you don't need
special links for modules, or classes, or methods. That could be
particularly useful for TG if it meant that it could link to document on
other sites, maybe using the package as a key to a rool url, like
sqlobject points to http://sqlobject.org/lib/, MochiKit to
http://mochikit.com/doc/html/MochiKit/, etc.
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
--
Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org
