<br><br><div class="gmail_quote">On Mon, Mar 28, 2011 at 10:14 AM, George Pauly <span dir="ltr"><<a href="mailto:george@ringdevelopment.com">george@ringdevelopment.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im"><br>
On Sun, Mar 27, 2011 at 8:57 PM, Glyph Lefkowitz<br>
<<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>> wrote:<br>
><br>
> On Mar 23, 2011, at 9:34 PM, Glyph Lefkowitz wrote:<br>
><br>
> > <<a href="http://twistedmatrix.com/%7Eglyph/sphinx-preview-11.0pre1/" target="_blank">http://twistedmatrix.com/~glyph/sphinx-preview-11.0pre1/</a>><br>
><br>
><br>
> Anyone have comments about this? With all the recent<br>
> excitement about the docs, I thought there would be a much<br>
> more active thread here!<br>
><br>
<br>
</div>Looks great, the world needs this.<br>
<br>
<br>
To make it even better:<br>
<br>
Search caption ("Quick Search") should be "Search TwistedMatrix.com" or<br>
"Search Twisted Documentation" or whatever the search space is/will be.<br>
</blockquote><div><br>Noted. This is a good idea.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
The different amounts of detail and subdivisions among TOC topics are a<br>
little clumsy with the heirarchical UI. For example, Twisted IM<br>
Documentation seems to have an extra layer of indirection. Would an<br>
expando menu of some sort be possible? It seems a little rough to go<br>
through a series of menu pages.<br></blockquote><div><br>I'm not sure exactly what you mean here. I agree that the naming of documents is a bit confusing, and intend to address that following the actual conversion. This has to do with the fact that in some places Sphinx is picking up the actual name of the document, and in other places it's picking up the link text from what was previously an <a> tag in the Lore sources. Also some documents are just poorly named or have outdated names. (e.g. Twisted IM rather than Twisted Words).<br>
<br>Can you clarify what you meant by "an extra layer of indirection?"<br><br>I think an "expando" menu is a bad idea, assuming I understand what you mean here. Or rather, I think that there are some structural issues which need to be solved, and an "expando" menu wouldn't solve them.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
"This Page / Show Source" (on rhs menu) could be confusing in context<br>
(it's not the Twisted source). Is this for Sphinx debugging? It<br>
doesn't seem useful to someone seeking Twisted docs.<br></blockquote><div><br>This is easily removed with a config setting in the Sphinx config file, though I find it helpful when writing docs. Most Sphinx sites seem to leave it in, though if others find it confusing we can remove it.<br>
<br>Alternatively, perhaps we could just change the link text to clarify it a bit. Something like "show Sphinx source?" "Show ReST source?"<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
Should Lore docs be removed from the menu? - this will be confusing.<br>
</blockquote><div><br>The Lore docs will disappear when the Lore docs (and Lore itself) are removed from trunk. <br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
"index" link goes to empty page<br>
<div class="im"></div></blockquote><div><br>The index is generated by default mostly from docstrings. Twisted is not currently using Sphinx's docstring utilities, as all of Twisted's docstrings use epydoc markup, rather than Restructured Text.<br>
<br>There are several ways we can go with this, but I consider it low priority, since the current docs have nothing like an index at present.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im">
><br>
> Thoughts about whether we should link it from the front page?<br>
><br>
><br>
<br>
</div>Definitely link it.<br>
<br>
<br>
hth,<br>
<br>
George<br>
<font color="#888888">--<br>
George Pauly<br>
Ring Development<br>
<a href="http://www.ringdevelopment.com" target="_blank">www.ringdevelopment.com</a><br>
</font><div><div></div><div class="h5"><br>
<br>
_______________________________________________<br>
Twisted-Python mailing list<br>
<a href="mailto:Twisted-Python@twistedmatrix.com">Twisted-Python@twistedmatrix.com</a><br>
<a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python" target="_blank">http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python</a><br>
</div></div></blockquote></div><br>