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

[Kevin Horn]

On Thu, Jan 21, 2010 at 3:03 AM, <exarkun at twistedmatrix.com> wrote:

>
> On IRC last night I brought up the idea that we could skip the
> conversion to ReST and use Sphinx with xhtml input documents.  The
> conclusion seemed to be that this might be difficult, but no one was
> really sure what work would be involved in this approach.  Kevin's
> already put a lot of effort into the conversion.  It would be nice if
> someone else could investigate this.
>

>From a docutils point of view, I _think_ it would involve creating a
docutisl "Parser" object, which could read the Lore sources and translate it
into a "doctree" of nodes.  From there you could generate the output in
whatever format is supported by docutils.  This would be doable in theory,
but I don't think it would be trivial or even easy, and then you'd have
another tool to maintain until the end of time.

Sphinx adds a bunch of extensions and conventions on top of docutils proper,
and I have little to no idea of what would be involved in handling those
issues.



> >
> >>   - Foolscap 0.5 was released today, which made me wonder what they
> >>use for
> >>     docs...and it's Lore.  I brought this up on IRC, and it was
> >>suggested
> >>     by many that Lore should stick around even after the conversion
> >>according
> >>     to the standard Twisted compatibility policy, to give anyone who
> >>still
> >>     uses it time to migrate.  This sounds like a fine idea to me.
> >>     Any thoughts?
> >
> >Since nobody really uses lore's API, the same compatibility policy
> >doesn't really apply.  In lore's case, I would say that the policy
> >should be that we include it with X more releases just for packaging
> >convenience, but stop doing maintenance immediately.
>
> As long as someone wants to do maintenance, I don't see any reason to
> stop them from doing it.  We might mark all the Lore tickets lowest
> priority or otherwise signal that some subset of the "core" developers
> aren't interested in maintaining it.... but then, how would that be any
> different from the status quo?
>
> Jean-Paul
>
>
If someone wants to maintain Lore, I certainly have no objection, but I
don't think anyone really does.  And it's not like it won't still be in the
SVN repos back in the history someplace, even if it were to be "removed"
from trunk.

I don't have strong feelings about it either way, but my feeling is Lore
should maybe be officially deprecated for a release (or 2, 3, etc.) and then
"removed" from trunk, and if someone wants to maintain it themselves, they
can fork it and deal with it outside the Twisted project.  Or it can be
"resurrected" later on if someone wants.  At the very least, don't force
users to install Lore along with the rest of Twisted once Lore is out of
general use.  Maybe it could be a separate package like web2?

But if it were just up to me, I would just get rid of it, to avoid taking up
developer time, cluttering up trac with open tickets, etc.

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20100121/2d810c8b/attachment.html>