[Twisted-Python] Proposal (almost) to switch from Lore to Sphinx

[Kevin Horn]

Back in July, there was a long discussion thread regarding Twisted
Documentation, and the idea of switching to Sphinx came up.  Here's
probably the culmination of that thread:

http://twistedmatrix.com/pipermail/twisted-python/2009-July/020114.html

To summarize, Glyph laid out the following items that would need to happen
in
order for Twisted to move from Lore to another documentation system:

1. Someone would have to volunteer to maintain the documentation
   infrastructure and teach others to use it.

2. Submit a complete proposal outlining benefits for the move so that it
   could be discussed rationally without having to chase down lots of little

   bits in email, irc, etc.

3. Address the transition process.

So I went away and did some thinking, and some research and some
experimenting, and I decided that I really want this to happen.

So I am hereby volunteering to manage a Sphinx-based documentation
infrastructure (should there eventually be one) for the Twisted project
as well as the transition to said system.

I have written up a proposal here:

http://twistedsphinx.funsize.net/proposal.html

that I think addresses at least the main points of what should need to
happen
in order to move from Lore to Sphinx.  It's not quite finished, but I think
it's close enough for people to start discussing it.  In particular, there
are a few claims I've made about Lore and it's capabilities that I'm not
quite sure of (just search for the question marks).

I would very much like to get some feedback from the community (especially
the core developers) on this proposal. I'd especially like to hear about:

- things which are not addressed and should be.
- anything that is addressed in the proposal, but you think should be done
  in a different way.
- Lore's capabilities.

Please let me know what you think.

Thanks,

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20091111/522a46cc/attachment.html>