[Twisted-Python] Lore to Sphinx Conversion Progress Report 4

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Thu Jan 21 04:03:04 EST 2010


On 03:57 am, glyph at twistedmatrix.com wrote:
>On Jan 19, 2010, at 4:33 PM, Kevin Horn wrote:
>>This time I think I'm gonna skip saying how I haven't gotten as much 
>>done as I would like...oh darn.
>>
>>Anyways, time for another gripping installment...
>>
>>   - due to ReST's insistence on "inline markup" being surrounded by
>>     whitespace or certain special characters, there are a lot of 
>>places where
>>     such inline markup gets jacked up, by not including whitespace in 
>>front of
>>     it.  If I put whitespace in front of everything though, my 
>>indentation
>>     handling gets jacked up and about 400+ Sphinx build warning 
>>result.
>>     Not sure if I should spend the time to make whitespace handling 
>>really
>>     smart or if these should just be fixed manually post-conversion.
>
>I don't really understand this problem.  What do you mean about making 
>whitespace handling really smart?  Isn't this the sort of detail that 
>docutils is supposed to handle for you?
>>
>>   - some of the Lore source files have nested "inline markup", which 
>>ReST
>>     disallows.
>
>Ugh.  So ReST can't do this?  That's pretty lame.
>>       - just handle the outside level of nesting (what I'm doing now) 
>>and
>>         fix any problems manually post-conversion.
>
>I'm assuming there are very few instances of this, so that sounds fine.

On IRC last night I brought up the idea that we could skip the 
conversion to ReST and use Sphinx with xhtml input documents.  The 
conclusion seemed to be that this might be difficult, but no one was 
really sure what work would be involved in this approach.  Kevin's 
already put a lot of effort into the conversion.  It would be nice if 
someone else could investigate this.
>
>>   - Foolscap 0.5 was released today, which made me wonder what they 
>>use for
>>     docs...and it's Lore.  I brought this up on IRC, and it was 
>>suggested
>>     by many that Lore should stick around even after the conversion 
>>according
>>     to the standard Twisted compatibility policy, to give anyone who 
>>still
>>     uses it time to migrate.  This sounds like a fine idea to me.
>>     Any thoughts?
>
>Since nobody really uses lore's API, the same compatibility policy 
>doesn't really apply.  In lore's case, I would say that the policy 
>should be that we include it with X more releases just for packaging 
>convenience, but stop doing maintenance immediately.

As long as someone wants to do maintenance, I don't see any reason to 
stop them from doing it.  We might mark all the Lore tickets lowest 
priority or otherwise signal that some subset of the "core" developers 
aren't interested in maintaining it.... but then, how would that be any 
different from the status quo?

Jean-Paul



More information about the Twisted-Python mailing list