<br><br><div class="gmail_quote">On Mon, Nov 16, 2009 at 3:11 PM,  <span dir="ltr">&lt;<a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a>&gt;</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>
&gt;&gt;<br>
&gt;er, sorry, forgot to post the link...<br>
&gt;<br>
&gt;here it is:<br>
&gt;<a href="http://twistedsphinx.funsize.net/" target="_blank">http://twistedsphinx.funsize.net/</a><br>
<br>
</div>Thanks.  It&#39;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&#39;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 &quot;new look&quot; effect.  </blockquote><div><br>Wet blanket away!  Every project needs a good &quot;devil&#39;s advocate&quot;.<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&#39;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 &quot;tier&quot; 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&#39;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 &amp; 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&#39;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 &quot;typeset&quot; a printed version of the Python Tutorial with it)<br><br>You&#39;re absolutely right that just giving the docs a &quot;facelift&quot; wouldn&#39;t require nearly so much effort, but I don&#39;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&#39;ll start with one possibility - the index.  Am I right in thinking<br>
this is automatically generated?  This is something Lore isn&#39;t currently<br>
capable of (there&#39;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&#39;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 &quot;index&quot;. :)<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 &quot;table of contents&quot; (which shows up in the index.html, contents.html, etc.).  Not trying to nitpick here, just trying to be clear.  If I&#39;m incorrect in assuming that&#39;s what you meant, then you can ignore the following and correct me, and we&#39;ll go from there.<br>
<br>In the meantime, I&#39;ll assume we&#39;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 &quot;toctree&quot; 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&#39;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 &amp; 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&#39;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&#39;s no reason we&#39;d need to do this in the final product.<br>
<br>Of course, if you mean the &quot;index&quot; index, then the answer is entirely different :)<br><br>Kevin Horn<br></div></div><br>