I'm having to do the pydoctor vs. Sphinx vs. EpyDoc research anyway...I'll post it somewhere public and send a link/message to the list.
This was raised in July (in a thread you posted to ;).
http://twistedmatrix.com/pipermail/twisted-python/2009-July/ 020102.html
I knew I'd thought about it before! I've been slammed with other work since then and haven't had to face the "doc monster" again until now. I'm pulling docs together on several new modules/packages that have been factored out of a large code base and we have a complete mish- mosh. Not as big as Twisted, but much less organized. Twisted, and probably almost every project of similar size and, more particularly, age, has some level of doc fung. Back in the 'old days' the tools were sparse (or bad) enough that the Twisted project made some of its own; of course. So did lots of other people. Also, as time went on, more options (like wikis) came about and parts of the docs found their way into the mix. From reading back over that previous discussion, I realize that my main thought was to build a database of what is on hand, from all the various sources, then pulling them together into some sort of system where they could all be organized, filtered, and finally sent to *something* to come out done on the other side. As far as I know, there is no good answer available off the shelf. Maybe someone else knows of something? It could be that it's just something that has to be 'done.' And, done in a comprehensive (and/or extensible) enough way that it will serve the needs of other projects, too. I'm not sure (as I wasn't in July) what the next step is, but it might be as simple as writing a simple DocCollector app that pulls everything into one database, cross references and indexes it, and gets it into some sort of visual presentation that we can start to make sense of the whole thing with. Maybe the first step would be to pull together a list of "everywhere we know Twisted docs are known to live" and start pulling it in to see where that leads... Where would be the best place to put the "collector" page where everyone would know to look for it and would be able to contribute to it (some wiki, but which one?). Thanks, S