Bob Ippolito wrote:
Here's some examples that cover all of the cases that mochi_name
currently handles:
:mochiref:`MochiKit.DOM.computedStyle(elem, style, mozillaEquivalentCSS)`
<a href="DOM.html#fn-computedstyle">computedStyle(elem, style,
mozillaEquivalentCSS)</a>
:mochiref:`computedStyle(elem, style, mozillaEquivalentCSS)`
<a href="#fn-computedstyle">computedStyle(elem, style,
mozillaEquivalentCSS)</a>
:mochiref:`MochiKit.DOM`
<a href="DOM.html">MochiKit.DOM</a>
It's of course rather specialized, but it's very easy to cut and paste
the role I've written and do something slightly different for another
purpose.
So, just taking the mochi out, you could have :ref:`object_name(stuff
that gets ignored)`, and :def:`object_name(stuff that gets ignored)` on
the other end. I don't know if there's any need to differentiate
between class, method, and function. Well, if it knows about
containment, so that it knows when a method is contained in a class and
can create the fully qualified name.
The def turns into a anchor and gets registered in some index used
during the build process. The ref is probably left dangling until all
the defs have been found -- since I expect that in Python source it will
be harder to figure out where the target is, since you have modules,
classes, functions, and methods. And later you might even let people
jump directly to source or whatnot. And you might want backrefs. All
that indexing stuff. Toss it in a SQLite database as you parse.
On the second run through you could probably use a regular expression to
find the :ref: tags (assuming you write them out in some way that is
easily recognizable). No need to do full XML parsing at that stage,
considering the output is highly regular, IMHO. *Or*, you could do the
indexing without generating *any* documentation, and just cache that
heavily to avoid the double-reST-parsing overhead. Or you could keep
the entire parsed documentation in memory and write it out only after
you've finished. Lazy me says regular expression.
One issue is that Pudge doesn't use reST for signatures and whatnot --
that structure is created in Kid. But that just means a custom bit for
adding its structure to the index.
On the other hard, one /theoretical/ advantage that PythonDoc has is
that it would be possible to extend developer tools (IDEs and whatnot)
to understand its tags, which contain semantic information that would
be useful for tool tips, completion, etc. That's at a cost though,
just like manifest typing in general. Practically, I can't imagine
that happening any time soon.
Seems like you could do the same for reST too, given a specific set of
conventions. Emacs even knows about reST literal blocks, and will
properly indent source inside them. But I don't care about IDEs, so
whatever ;)
--
Ian Bicking | [EMAIL PROTECTED] | http://blog.ianbicking.org
