[Twisted-Python] Re: [Twisted-web] Re: Actual Useful Post
Michael Hudson
mwh at python.net
Wed Jan 25 05:13:06 EST 2006
Jean-Paul Calderone <exarkun at divmod.com> writes:
> On Mon, 23 Jan 2006 17:14:32 +0000, Michael Hudson <mwh at python.net> wrote:
>>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.
>
> +1 for using a mechanism associated with an existing Python idiom
The pb classes are not in an __all__ currently. I also think that
__all__ is an abomination, but I'll try to suppress that :)
>>
>>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).
>
> -1 for magic markup embedded in source files
There's going to need to be some magic/special casing at some level,
to deal with twisted.python.components.Interface.
Cheers,
mwh
--
Screaming 14-year-old boys attempting to prove to each other that
they are more 3133t than j00.
-- Reason #8 for quitting slashdot today, from
http://www.cs.washington.edu/homes/klee/misc/slashdot.html
More information about the Twisted-Python
mailing list