[Twisted-Python] Let's talk about maintaining Lore (and validity of tickets)

Kevin Horn kevin.horn at gmail.com
Fri Mar 1 10:44:26 MST 2013


On Fri, Mar 1, 2013 at 2:29 AM, Glyph <glyph at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20130301/01391c1b/attachment.html>


More information about the Twisted-Python mailing list