On Wed, Dec 30, 2009 at 2:05 PM, Kevin Horn <kevin.horn@gmail.com> wrote:
Hello again, and welcome to another update on the Twisted Lore to Sphinx conversion project.

Current Sphinx results are in the usual place at: http://twistedsphinx.funsize.net/

Here's what's new:

- The lore2sphinx conversion script is now up on bitbucket.  You can find it here: http://bitbucket.org/khorn/lore2sphinx/ .
  Special thanks to Steve Steiner (ssteinerX) for helping out a bitbucket newbie.

- lore2sphinx now reads input and output directories from a config file.  The config file can have one or more "profiles", each of which contains config info for a set of documentation. At present, the script just uses the default profile (set in the config file), but I'll add a command line switch to specify the profile Real Soon Now (tm), which will make it easy to use a single config file for multiple projects (e.g. twisted, nevow, mantissa, etc.)

- lore2sphinx has also been refactored a bit, which solves a lot of whitespace handling issues. The Sphinx build now gives fewer than 100 errors (currently 65, started off in the 500-600 range)!  Hooray!  Still, not all of the output is fully correct, and some tags (notably tables) are still unhandled.

- I still haven't started any work on a theme...I'll get to it eventually, unless someone else does first.  Any volunteers?

- Divmod docs: new config file support is a step in this direction, look for something soon...

- PyOpenSSL docs: kind of a sideline to this so I haven't really moved forward on this yet, but I will eventually

If anyone out there would like to help out, I can certainly use the assistance.  Lore2sphinx could probably use some extra eyeballs and brains looking at it, thought the basic structure is pretty much laid out.  Any ideas/comments/criticisms welcome.

If you're intimidated by the idea of working on the actual lore2sphinx conversion script (or just don't want to), here's some other stuff that needs doing:

- work on a twisted (or Divmod) Sphinx theme which at least mostly matches the website (or the Divmod website)
- identify branches which have lore patches in them
- identify tickets which propose to fix/modify Lore functionality
- identify wiki pages that need to be changed, and the necessary changes
- make suggestions on the overall conversion process, as documented in the proposal.

I'm sure I'll manage to get all this done eventually, but with more people, it will get done sooner.  And sooner is better. :)

If you'd like to help out with one (or more) of these tasks, just give a shout here, or email me off-list.


Kevin Horn

Another quick update...

- lore2sphinx now accepts a command line parameter to specify which config profile to use
- added "stub" sphinx projects for Divmod Nevow, Mantissa, and Epsilon.  I've converted the docs for these projects and built them (mostly) successfully, but I haven't published them anywhere yet (coming soon).  Have I missed any other Divmod projects with Lore docs?

Kevin Horn