On Jan 23, 2006, at 4:11 PM, Ian Bicking wrote:
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.
I don't think you can nest roles, I also can't imagine why you'd want
to...
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.
That doesn't look too bad, except for the HTML. Ick.
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.
You can do that with just about anything. In fact, the MochiKit
make_docs.py script does something awfully close to that. References
that start with "MochiKit." refer to other modules of MochiKit, so
they end up at named anchors on other HTML pages. References that
aren't fully qualified just point at a named anchor. It also
prettifies the output of the reference such that the user doesn't see
the fully qualified name, since that's generally just visual clutter.
In other words, if the mochi_name function was a generic function or
had some kind of registry, it could easily point elsewhere in URI
space based on upon arbitrary rules as needed.
-bob
