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

Glyph Lefkowitz glyph at twistedmatrix.com
Sat Jul 10 23:39:56 EDT 2010

On Jul 10, 2010, at 10:48 PM, Kevin Horn wrote:

> Let's just say there's a reason that there's not an official docutils tool to _create_ restructuredText.

Is that really true?  If so, it concerns me.  Isn't that what docutils.writer.UnfilteredWriter does?  Even if not, it should be possible - reasonable, even - to write a docutils.writer.Writer which just emits reST.

Sphinx is a nice tool, but reST's grossness bothers me more and more.  If there are really no tools which can emit reStructuredText from a data structure, that means we have no hope of ever processing our source documentation in deterministic, correct ways (as a trivial example, let's say we wanted to change the name of a package).  It's not a lot of fun to process XML documents, but there are plenty of APIs to do it and to be sure that the output is still XML when you're done.

This is really a theoretical concern (in the years we've been using lore, we never really managed to use any XML tools with it), and on balance all the features that sphinx brings to the table are almost certainly worth living with it, but it still bugs me.  Where should I file and/or vote for a bug report or feature request?  Is this sphinx's problem, docutils, or both?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20100710/4030fa97/attachment.htm 

More information about the Twisted-Python mailing list