[Twisted-web] Re: Actual Useful Post

[Michael Hudson]

Christopher Armstrong <radeex at gmail.com> writes:

> Anyway, as I said earlier, the thing that needs the most work that's
> related to releases is web site and documentation stuff. API docs are
> basically impossible to generate for mortals right now. I've heard
> some people can get epydoc to work if they do crazy stuff, but it's
> not worked for me in a long time. I'd be impressed if someone can get
> API docs being generated on a regular basis. It'd be especially nice
> if we can get the web site updated with these docs on a regular basis,
> in both per-release and "in development" doc sections. Same goes for
> the Developer Guide.
>
> If anyone wants to help out with these (but *not* another web site
> redesign, please), then I'd be glad to consult.

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?

The boring bit of the task (for me, at least) is HTML generation.  I'd
love some help with this :) I guess I should get on IRC and talk about
what people actually want/need from these tools, but I'm at a PyPy
sprint this week so I'm *slightly* busy...

Cheers,
mwh

-- 
  Considering that this thread is completely on-topic in the way only
  c.l.py threads can be, I think I can say that you should replace
  "Oblivion" with "Gravity", and increase your Radiohead quotient.
                                      -- Ben Wolfson, comp.lang.python