[Twisted-Python] Lore to Sphinx Conversion Progress Report

[Kevin Horn]

On Thu, Dec 3, 2009 at 10:11 AM, Glyph Lefkowitz <glyph at twistedmatrix.com>wrote:

>
> On Dec 3, 2009, at 10:06 AM, exarkun at twistedmatrix.com wrote:
>
> I want some experience with Sphinx so that can verify the premise that
> Sphinx is better than Lore.  So, the experience isn't necessary for the
> conversion, it's necessary for me to be comfortable that the conversion
> is a good idea.
>
>
> Oh.  I am definitely taking that as a given.  Or rather: having frequently
> interacted with the output of both sphinx and lore, I was already confident
> that it was better than Lore in most ways before we began this conversation.
>  I had a few specific misgivings, which Kevin has since addressed.
>
> Sphinx clearly has the *features* that we need; Kevin's analysis looks
> pretty thorough, and even the current error-laden converted documentation
> serves as a reasonable proof of concept.  Plus, the plan specifically
> includes resolving the remaining issues with that documentation as a
> prerequisite to getting it merged.
>
> So while I could believe that there will be bad things about Sphinx which
> may surprise me, I find it hard to believe that I could be surprised by any
> bug in Sphinx so awful that it would be *enough worse* than Lore to make
> continuing to maintain Lore a preferable option, given the presence of a
> documentation maintainer willing to do the drudgework of conversion.
>
> That said, it might be a good idea to do the Divmod project conversions
> first for other reasons.  They have less documentation, so there's less to
> review, and the process could be completed more quickly, letting us get some
> benefit out of the process earlier on.  Since these projects are the only
> known remaining users of lore, we could get rid of lore immediately when
> twisted itself is converted, rather than letting it linger until its users
> have converted.
>
>
I think maybe I'll try to do a quickie conversion on one of the Divmod
projects (probably Nevow)  in the next couple of days.  I'm not planning on
doing a theme or anything yet...just the content conversion, followed by
manual cleanup.

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20091203/8f0c54fb/attachment-0001.htm