[Twisted-Python] Re: [Twisted-web] Re: Actual Useful Post

[Andrew Bennetts]

[moving this to twisted-python, where it clearly belongs]

Michael Hudson wrote:
[...]
> 
> Well, I've had a quick pop at the interesting bit of this task while
> travelling over the weekend: using the compiler module I can extract
> the docstrings and class hierachy of all the stuff in the Twisted
> source.  It's a touch fragile, but seems to work for all the
> constructions used by Twisted.
> 
> One issue is classes that are defined in one file but generally used
> from another, for example twisted.spread.jelly.Serializable is often
> (always?) imported as twisted.spread.pb.Serializable.  Where should it
> be documented it?

See http://twistedmatrix.com/bugs/issue1143.  It has the possibly useful
suggestion of using __all__ to determine where an aliased thing should be
documented.

Another option is some sort of explicit hint to the doc extractor, e.g. a define
no-op call like "alias('Serializable')" in the relevant module that the doc
extractor could notice.  Or keep an explicit list of overrides in a file...

-Andrew.