[Twisted-Python] Lore, Sphinx, and getting to the finish line (was: re: lore and tickets and other stuff)

Tom Prince tom.prince at ualberta.net
Sat Mar 2 03:18:12 EST 2013

> 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.

Well, the way the cut-over will eventually happen is that a
ticket+branch is given a postive review.

So you say that "[you] have [...] been willing to make the cutover", without
having put an associated ticket into review sounds somewhat like
abandoning the development process.

> Despite numerous attempts to prod someone into responding to my requests
> for clarification ;) on the ticket, I never got any response.

Side note: The best way way to get a response to a ticket is probably to
put it into review.

> Specifically, I could never get an answer on whether the sphinx build tool
> should require whomever was running it to specify a version or whether the
> tool should guess.  The existing tools (at the time, I haven't looked at
> the current state of these) do/did both, in different places.

Having a look at the current release automation tools, it looks like the
only one that takes a version is `change-versions`, and the rest of the
tools use the version from the tree.

>>  *I* can't even remember how to do the math to associate one of the results
>> in <http://buildbot.twistedmatrix.com/builds/sphinx-html/>.

I've update the buildbot to create a link from the build to the
generated documentation.

>>    1. We need to have release-automation tools that allow developers to
>>    produce a release, including documentation.  These tools need to be
>>    subjected to the same development process as the rest of those tools, which
>>    is to say the same process as for the rest of Twisted.
> I (sort of) understand the desire for this, but it seems pretty weird to be building
> what is essentially a wrapper for an existing tool, along with tests for
> said wrapper,

If the command is now, and always will be, just 'sphinx-build .' then we
might be able to get away without doing this, but since sphinx isn't
under our control, we can't insure that. Thus, we need somewhere to
record how to run sphinx-build. If we have a wrapper, then we have an
obvious place to record that information.

This also gives us an easy place to add things like using a different
template when building docs on the buildbot, as opposed to the release
documentation, for example.

> 4) Get someone to use something less hackish than what's currently building
> the Sphinx docs on the buildbot,

I can help with this.

> and preferably in such a way that the results of those builds could be
> published somewhere and have persistent links.

I'm not sure if this makes sense to keep all the old builds around. It
only takes ~2 minutes to regenerate them, as needed.

> My plan was that we'd set up something where the Sphinx docs would get
> generated and published someplace for every buildbot build

We currently do this for every trunk revision, and it is possible to do
by hand for any branch version. It is straightforward to add this to the
list of builds that get done by running force-build.py.

> So.  I guess at this point the question is whether to try and go with
> what's there (lore2sphinx) or finish up the "new stuff" (lore2sphinx-ng +
> rstgen).  I think 3-6 in my above plan need to happen in any case, and I
> think those will be much easier with lore2sphinx-ng+rstgen.

More information about the Twisted-Python mailing list