[Twisted-Python] Lore to Sphinx Conversion Progress Report 3
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. Thanks! Kevin Horn
Hi Kevin, On 30 Dec 2009, at 21:05, Kevin Horn wrote:
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
I can work on identifying those tickets and branches in Twisted, but should I put that info in a ticket or on a Twisted wiki page? And should the tickets with Lore enhancements be closed immediately or listed first? Thanks for all your work! Cheers, Thijs
On Wed, Dec 30, 2009 at 2:40 PM, Thijs Triemstra | Collab <lists@collab.nl>wrote:
Hi Kevin,
On 30 Dec 2009, at 21:05, Kevin Horn wrote:
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
I can work on identifying those tickets and branches in Twisted, but should I put that info in a ticket or on a Twisted wiki page? And should the tickets with Lore enhancements be closed immediately or listed first?
I'm open to suggestions as to where to list the tickets. A Trac ticket or a wiki page would certainly work, or we can integrate the list into the proposal document. What might be a good solution though is to just add a Trac keyword to all of the relevant tickets, or even just identify a specific search for them in Trac (is it enough to just do a custom search for Lore component tickets?). I think we should just come up with a list as a first step. Though I really hope to complete the conversion before too much longer, you never know what could happen, and if it gets delayed significantly, it might be useful to still have those tickets open.
Thanks for all your work!
Cheers,
Thijs
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.
Thanks!
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
On Dec 30, 2009, at 7:07 PM, Kevin Horn wrote:
Another quick update...
Keep up the good work!
- 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?
Nope, that's all of them.
participants (3)
-
Glyph Lefkowitz -
Kevin Horn -
Thijs Triemstra | Collab