<br><br><div class="gmail_quote">On Mon, Nov 16, 2009 at 3:11 PM, <span dir="ltr"><<a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="im">On 06:09 pm, <a href="mailto:kevin.horn@gmail.com">kevin.horn@gmail.com</a> wrote:<br>
>><br>
>er, sorry, forgot to post the link...<br>
><br>
>here it is:<br>
><a href="http://twistedsphinx.funsize.net/" target="_blank">http://twistedsphinx.funsize.net/</a><br>
<br>
</div>Thanks. It's good to be able to see (at least an early draft of) what<br>
the outcome of this proposal will be.<br>
<br>
I'm glad the reactions have been good so far, but I want to be a wet<br>
blanket for a moment and suggest that we try to avoid being influenced<br>
excessively by the "new look" effect. </blockquote><div><br>Wet blanket away! Every project needs a good "devil's advocate".<br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
It would be easy to give the<br>
existing documentation a face lift without switching systems entirely -<br>
it's just a matter of editing the template and/or the css. What are the<br>
other benefits of the Sphinx output, in particular, the ones which it<br>
would be difficult to achieve with Lore?<br></blockquote><div><br>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:<br>
<br>- 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)<br>
- a much larger user base, and clear extension API, which allows us to take advantage of existing extensions, etc.<br><br>Now having said that, switching to Sphinx *output* does have some advantages (though by themselves they might not be compelling enough to switch).<br>
<br>- better navigation (prev & next links, table of contents)<br>- JS-based full text search<br>- CHTML output (very nice for those of us who use Win32...though I realize we're a minority here in the Twisted world)<br>
- 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)<br><br>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.<br>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
I'll start with one possibility - the index. Am I right in thinking<br>
this is automatically generated? This is something Lore isn't currently<br>
capable of (there's a branch which addresses this, but I suspect it is<br>
far too much of a mess to ever merge, so we can ignore it). Going along<br>
with this, how much control do we have over how the index is generated?<br>
Some of what shows up here probably doesn't merit being displayed as<br>
prominently as this - for example, the historical documents are mostly<br>
of, well, historical interesting. What options do we have for changing<br>
how these are presented?<br>
<br>
Jean-Paul<br>
<div><div></div><div class="h5"><br>
<br></div></div></blockquote><div>Hmmm...this depends on what you mean by "index". :)<br><br>There are (at least) 3 meanings of index as it relates to Sphinx. <br><br>- general index - currently empty<br>- module index - currently empty and, in fact, missing<br>
- search index - auto-generated and used for the JS-based full text search feature<br><br>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.<br>
<br>In the meantime, I'll assume we're talking about the table of contents (TOC).<br><br>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:<br>
<br>| ..toctree:<br>| <br>| projects/conch/index<br>| projects/core/index<br>| ..etc<br><br>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.<br>
<br>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.<br>
<br>Of course, if you mean the "index" index, then the answer is entirely different :)<br><br>Kevin Horn<br></div></div><br>