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

Michael Hudson mwh at python.net
Mon Jan 23 12:14:32 EST 2006


Andrew Bennetts <andrew-twisted at puzzling.org> writes:

> [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.

Hmm, that could work.  Although having the "official" name for a class
different from its __name__ is fairly horrible :)

> 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...

These also could work, as could magic comments (though that would be
marginally harder).

Cheers,
mwh

-- 
  What the semicolon's anxious supporters fret about is the tendency
  of contemporary writers to use a dash instead of a semicolon and
  thus precipitate the end of the world.
                               -- Lynne Truss, "Eats, Shoots & Leaves"





More information about the Twisted-Python mailing list