[Twisted-Python] Re: [Twisted-commits] Adventures in Epydoc: Stop The Hurt, part 1: The end of privatization

[Christopher Armstrong]

On Mon, Aug 11, 2003 at 11:03:07AM -0500, radix CVS wrote:
> Modified files:
> Twisted/admin/epyrun 1.20 1.21
> 
> Log message:
> Adventures in Epydoc: Stop The Hurt, part 1: The end of privatization

Some of you have been complaining about the huge size of the API
documentation in recent releases. I've discovered that the reason for
this was most likely a work-around that spiv did so that there are
HTML files for every single method in the documented code (they each
just contained a tiny snippet of HTML that redirected to the canonical
location of the documentation for that method). Assuming 4k blocks on
your filesystem, all of these tiny files added to an immense amount of
wasted space. 

I haven't taken this out, however: I've cut the size of the
documentation in half by removing the "private" cruft. epydoc by
default generates a separate tree of documentation that contains
everything the `public' tree has, but also things it deems "private",
like methods that begin with "_", or objects that are not listed in a
module's "__all__". I've hacked it so that *everything* is considered
`public' by epydoc, and it no longer generates that duplicate
`private' tree.

Next up on my todo for the documentation is to try to get epydoc to
stop documenting non-Twisted things. Currently it's documenting many
things from the Python standard library as well as third-party
libraries that Twisted uses. All of this extra documentation builds up
to about 8.8MB of wasted space, assuming 4k blocks. After that, I'm
going to look into getting the docs building with Python 2.3 (Cory
Dodt has reported problems with code using the twisted.python.hook
module). Also, I'll try to get the Twisted version number on every
page of docs.

-- 
 Twisted | Christopher Armstrong: International Man of Twistery
  Radix  |          Release Manager,  Twisted Project
---------+     http://twistedmatrix.com/users/radix.twistd/