This time I think I'm gonna skip saying how I haven't gotten as much done as I would like...oh darn.<br><br>Anyways, time for another gripping installment...<br><br>Progress:<br> - tables are now handled (mostly) properly, thanks to Zeth at <a href="http://commandline.org.uk/">http://commandline.org.uk/</a><br>
- blockquote tags handled<br> - much improved whitespace/indentation handling<br> - some nicer styling thanks to Michael Thompson<br> - I've managed to convert the docs for the 3 Divmod projects with Lore <br> docs, though I've yet to put them up anywhere.<br>
<br><br>Oustanding issues:<br> - two files in the Lore source are not yet being converted, but it looks like <br> one of them is about to be removed <br> (<a href="http://twistedmatrix.com/trac/ticket/4188">http://twistedmatrix.com/trac/ticket/4188</a>), and it's not really a <br>
Lore doc anyways.<br> - due to ReST's insistence on "inline markup" being surrounded by <br> whitespace or certain special characters, there are a lot of places where<br> such inline markup gets jacked up, by not including whitespace in front of <br>
it. If I put whitespace in front of everything though, my indentation <br> handling gets jacked up and about 400+ Sphinx build warning result.<br> Not sure if I should spend the time to make whitespace handling really <br>
smart or if these should just be fixed manually post-conversion.<br> - cite tags still need handling...not hard, just haven't decided the best <br> way to do it yet.<br> - Themeing/styling: still mostly a TODO, though new styling looks a lot <br>
better than the default to my eyes. I'm starting to think that <br> eventually we might want to have 2 themes/styles...one to match the <br> trac-based website, and one for bundled docs (docs tarballs, CHM files, etc.)<br>
- auto-generated toctree directives are currently generated in alphabetical <br> order, which makes the "prev" and "next" links mostly make no sense<br> - some of the Lore source files have nested "inline markup", which ReST <br>
disallows. This can be handled by:<br> - fix the markup in the Lore source<br> - figure out some kind of supersmart auto-conversion for every possible <br> combination of nesting<br> - just handle the outside level of nesting (what I'm doing now) and <br>
fix any problems manually post-conversion.<br> - xhtml entities are not currently resolved...mostly because it makes <br> the build take a LOOOONG time. They can be though. This shouldn't <br> be a problem.<br>
- xhtml comments still need to be handled<br> - <code class="API"> tags need something better..right now they are just <br> the same as <code> tags...Sphinx has an upcoming feature coming in 1.0<br>
that would make this nice and maintainable in the long run, but I don't <br> know that I want to wait for it. I may try to "backport" the extension<br> or just come up with a separate solution.<br>
- some of the generated links need fixing <br> (e.g. links to directories, .py files)<br> <br>In other news:<br><br> - Foolscap 0.5 was released today, which made me wonder what they use for<br> docs...and it's Lore. I brought this up on IRC, and it was suggested <br>
by many that Lore should stick around even after the conversion according <br> to the standard Twisted compatibility policy, to give anyone who still <br> uses it time to migrate. This sounds like a fine idea to me. <br>
Any thoughts?<br><br><br>As always, the lore2sphinx code is here: <a href="http://bitbucket.org/khorn/lore2sphinx/">http://bitbucket.org/khorn/lore2sphinx/</a><br><br>And the sample output of the conversion process is here: <a href="http://twistedsphinx.funsize.net/">http://twistedsphinx.funsize.net/</a><br>
<br>Cheers,<br><br>Kevin Horn<br>