I'm not a big fan of any current python documentation tools. My concern is that they document the code as it appears in files, not as it is actually used at runtime.
Pydev's introspection is incredible. I was thinking that a little markup and the information that pydev has collected would be vastly superior to any current doc tools.
I haven't dug into Pydev's source at all, but how compatable would it be from this workflow? Is the introspector some library I can run, and then walk over the results? How much work would this be to get into a Python interpreter? Is it tied closely to Jython or the rest of the pydev editor?
I've been thinking about starting something like this for a little while. How feasible would it be?