On Wed, Apr 21, 2010 at 9:48 PM, <exarkun@twistedmatrix.com> wrote:

So about the conversion, I wonder if we can start to generate the Sphinx
version of the docs on buildbot sometime soon, and perhaps host them
alongside the current docs, as the first step in phasing out the current
version?

I suppose we could do this, if you think it would help.  Note that the lore2sphinx
script requires Python 2.6 and I think at least Sphinx 0.6.4 (I'm using 0.6.5).
 

How automated is the conversion process now?  Are errors reported such
that people could start looking at them and fixing the issues?  It seems
like you've done almost all of the hard work, and the rest is dealing
with some edge cases in lore or restructured text, and that might be
more easily spread out amongst more people.

Jean-Paul


I think the automatic conversion process has reached the point of diminishing returns.
I've got it down to about 13 warnings in the Sphinx build process, though there are still
some markup errors in the output.  Trying to make the conversion handle these seems
to just introduce more errors in other places.

In other words I think it's time to create a branch with the Sphinxified docs and do a manual review.

I've got a basic transition plan sketched out here:
http://twistedsphinx.funsize.net/transition_plan.html

That's just basically an outline of a plan Glyph and I hashed out during the Twisted sprint at PyCon.

Ideas and criticisms welcome.

Kevin Horn