[Twisted-Python] Proposal (almost) to switch from Lore to Sphinx

[Glyph Lefkowitz]

On Nov 11, 2009, at 5:52 PM, Kevin Horn wrote:

> Please let me know what you think.

Initial reaction: awesome!

I don't really care about the documentation format or tools, I'm just thrilled that someone is willing to step forward and maintain them in _any_ form.

Secondary reaction: automated testing of code and examples is great.  Necessary, even, especially for a new tool.  But doctests are not so much a testing plan as a disease that comes to infest your code.

(You are free to disagree with me about the utility or quality of doctest as a tool, but doing so on this mailing list is counterproductive, as my mind is pretty well made up.  Despite the fact that I have fond feelings towards lore's design, this is the *only* point I'd veto a migration over.)

Automated tests for documentation should look roughly like this:

    http://divmod.org/trac/browser/trunk/Nevow/nevow/test/test_howtolistings.py?rev=17299

but the stuff that does "sys.modules.clear()" and so on should be a lot further away from the actual test cases.

The only thing that is necessary for testing like that to work is the ability to reference an external .py file as a code listing.  This is also a good thing because then users can just run the Python files straight in the examples directory, rather than copying some stuff from a web browser into a text editor, mucking around with path variables for a while, trying to make sure they got the indentation right etc.

Can sphinx do that out of the box?

Tertiary reaction, since I had to go to divmod.org to dig up that example: a migration plan should include the Divmod projects, especially Nevow, since a lot of people use that.  But, if there's an automated tool that can handle the Twisted conversion, there really shouldn't be any additional effort to just run it over the Divmod codebase and just check in the result.  The only real work will be in adjusting the buildbot.  This is really just an argument for an automated, repeatable conversion process rather than manual editing.