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

[Kevin Horn]

On Mon, Nov 16, 2009 at 3:11 PM, <exarkun at twistedmatrix.com> wrote:

> On 06:09 pm, kevin.horn at gmail.com wrote:
> >>
> >er, sorry, forgot to post the link...
> >
> >here it is:
> >http://twistedsphinx.funsize.net/
>
> Thanks.  It's good to be able to see (at least an early draft of) what
> the outcome of this proposal will be.
>
> I'm glad the reactions have been good so far, but I want to be a wet
> blanket for a moment and suggest that we try to avoid being influenced
> excessively by the "new look" effect.


Wet blanket away!  Every project needs a good "devil's advocate".


> It would be easy to give the
> existing documentation a face lift without switching systems entirely -
> it's just a matter of editing the template and/or the css.  What are the
> other benefits of the Sphinx output, in particular, the ones which it
> would be difficult to achieve with Lore?
>

Well, IMO, the absolute #1 benefit of using Sphinx over Lore is simply not
having to maintain Lore, which has nothing at all to do with the actual
output.  The next "tier" of advantages (again IMO) also have nothing to do
with the output, those advantages being:

- a more approachable document format (in the sense that I think there are
probably more people familiar with the Sphinx dialect of RestructuredText
than are familiar with Lore's subset of XHTML...and the number of Sphinx
users is growing)
- a much larger user base, and clear extension API, which allows us to take
advantage of existing extensions, etc.

Now having said that, switching to Sphinx *output* does have some advantages
(though by themselves they might not be compelling enough to switch).

- better navigation (prev & next links, table of contents)
- JS-based full text search
- CHTML output (very nice for those of us who use Win32...though I realize
we're a minority here in the Twisted world)
- Direct PDF output (somewhat immature and provided by a 3rd party
extension, but mature enough that someone has actually "typeset" a printed
version of the Python Tutorial with it)

You're absolutely right that just giving the docs a "facelift" wouldn't
require nearly so much effort, but I don't think it would buy us as much
with regard to the ultimate maintainability of the documentation.

I'll start with one possibility - the index.  Am I right in thinking
> this is automatically generated?  This is something Lore isn't currently
> capable of (there's a branch which addresses this, but I suspect it is
> far too much of a mess to ever merge, so we can ignore it).  Going along
> with this, how much control do we have over how the index is generated?
> Some of what shows up here probably doesn't merit being displayed as
> prominently as this - for example, the historical documents are mostly
> of, well, historical interesting.  What options do we have for changing
> how these are presented?
>
> Jean-Paul
>
>
> Hmmm...this depends on what you mean by "index". :)

There are (at least) 3 meanings of index as it relates to Sphinx.

- general index - currently empty
- module index - currently empty and, in fact, missing
- search index - auto-generated and used for the JS-based full text search
feature

However from you comments above I think you probably meant what Sphinx calls
the "table of contents" (which shows up in the index.html, contents.html,
etc.).  Not trying to nitpick here, just trying to be clear.  If I'm
incorrect in assuming that's what you meant, then you can ignore the
following and correct me, and we'll go from there.

In the meantime, I'll assume we're talking about the table of contents
(TOC).

RestructuredText (in a plain vanilla docutils install) does not have any way
of connecting documents together other than hyperlinks.  Sphinx defines a
"toctree" directive to get around this limitation.  This is a directive that
goes into your Sphinx source documents that looks something like this:

| ..toctree:
|
|    projects/conch/index
|    projects/core/index
|    ..etc

Typically these would be created manually in your Sphinx source, but in this
instance I am creating them using my conversion script which generates ReST
source from Lore source.

At Sphinx build-time, Sphinx expects every ReST source file to show up
someplace in one of these toctree directives, and will generate warnings if
a file doesn't. Sphinx gathers up the connections defined by these toctree
directives throughout the project into  a tree-shaped data structure and
uses this to generate the handy navigation links (prev & next), and also to
display all or part of the tree as a series of hyperlinks in a table of
contents format.  The depth of the tree displayed (or even displaying it at
all) is easily configurable.  Right now I'm showing quite a lot, because it
makes it easier to test my toctree-generating code, and it makes browsing my
output a bit simpler.  There's no reason we'd need to do this in the final
product.

Of course, if you mean the "index" index, then the answer is entirely
different :)

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20091116/31b49b4c/attachment.html>