On Fri, Mar 1, 2013 at 2:29 AM, Glyph <glyph@twistedmatrix.com> wrote:

Jean-Paul recently closed a Lore ticket as invalid, and suggested we have a discussion about Lore's future direction. This strikes me as a very good idea, and so I wrote a message which is a bit too long (for which I apologize) to kick that off.

I don't think these two paths (lore2sphinx and continuing to maintain lore) are necessarily mutually exclusive. Also I think it implies something about the current state of affairs that isn't accurate - e.g. that the Twisted team has agreed that Sphinx will surely replace Lore and that we are making progress on that process of placement more than we are maintaining Lore itself.

Unfortunately, I think it will be clear to anyone following its progress that lore2sphinx is unmaintained and the sphinx migration effort is stalled. Nobody has committed to <https://bitbucket.org/khorn/lore2sphinx> in a year and a half, about the same amount of time that <http://twistedmatrix.com/trac/browser/branches/sphinx-conversion-4500> has been idle as well. By contrast, <http://twistedmatrix.com/trac/browser/trunk/twisted/lore> has seen commits - albeit not many - within only a couple of weeks. So, empirically, we're already maintaining lore and lore2sphinx is currently "obsolete"; really the question should be if we want to reverse that path.

Some what orthagonal to your point, but this is incorrect. lore2sphinx was some time ago into "lore2sphinx-ng" and "rstgen".

https://bitbucket.org/khorn/lore2sphinx-ng

https://bitbucket.org/khorn/rstgen

This was initially done as an experiment in using a more explicit "formatting model" for the generation for the Sphinx docs (and somewhat due to _your_ prodding, Glyph), and so I didn't initially make a big announcement or anything.

Once it became apparent that it was actually going to work out better, I sent out some emails to those who had expressed interest in helping with the whole lore2sphinx project, though I don't believe I sent out anything to the twisted list in general, as I probably should have. I'll point out that I can count people who have shown interest in moving this forward on one hand, though.

And I've specifically mentioned that I had done said forking to you, Glyph, in IRC ;)

(though it's IRC after all...who remembers what happens in IRC?)

I thought I had put a notice up in the readme file in the lore2sphinx repo, but as it isn't there, I presume I either forgot, or never got it merged, or something.

So, totally my bad for not communicating better, but I have NOT given up on converting things from Lore into Sphinx.

(Nor do I intend to.)

Thinking about it, I suppose I've been somewhat reticent to do much communicating about any work I do on this, as what seems to happen is that it just gives everyone an excuse bring up some new objection to actually getting the conversion done. I hadn't really realized this consciously until just now, though.

I also have no objection if someone wants to complete the lore2sphinx work, but if the lore2sphinx buildbot were to die tomorrow and go offline, I wouldn't be particularly anxious to spend a lot of resources to fix it.

My position on this was always that if someone wanted to improve the documentation, they were welcome to do so, and if they wanted to use Sphinx to do it, that's great too. I just wasn't willing to tolerate any period where our toolchain was broken and we couldn't generate documentation for a release. And a good thing we didn't, by the way! If we had said "go ahead, pull the trigger, whatever, it's OK to break trunk for a little while!" we wouldn't have had any documentation toolchain for the last 2 years.

And since we didn't break the toolchain, I've been in no particular hurry. I've accepted that this will take approximately a billion years. So no rush.

On the other hand, I have at several points been willing to make the "cutover", and for various different reasons, been told it wasn't happening until things were closer to "perfect" (for some value of "perfect") than they were at the time.

The current output of the old lore2sphinx branch is functional, though has a few warts (mostly extraneous spaces in the output). These warts were apparently enough to block adoption.

It has been a pretty discouraging effort at times, I have to say, as I seem to garner agreement/support/buy-in/whatever for a particular course of action (e.g. getting 99% of the way there, and then fixing Sphinx markup manually, which was the original plan, way back when), and focusing my efforts in that direction. Then when we're ready to proceed on that basis, had another task/challenge/set of requirements/whatever added to the work that needs to be done. In fact I still think that if the Twisted community had actually wanted to, we could have switched over to Sphinx at the first PyCon Atlanta (2010?).

Anyway, I'm not giving up. If nothing else, I'll end up with a nice restructuredText-generating library. And if Twisted never ends up adopting Sphinx as a doc tool, eventually I'll still be able to read the Twisted docs in a format that I can navigate and doesn't hurt my eyes to look at. :)

But I'd really rather see Twisted adopt Sphinx, and get rid of Lore.

Help accepted.

Kevin Horn