<br><br><div class="gmail_quote">On Sat, Jul 10, 2010 at 2:40 AM, Tim Allen <span dir="ltr"><<a href="mailto:screwtape@froup.com">screwtape@froup.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">On Sat, Jul 10, 2010 at 02:58:40AM -0000, <a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a> wrote:<br>
> At last I've got a buildbot set up generating the sphinx docs. The<br>
> build results can be seen here:<br>
><br>
> <a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/</a><br>
><br>
> (or with a different revision number for different revisions; the<br>
> containing directory is browseable).<br>
><br>
> It would be great if everyone could go look around and report any<br>
> problems you see.<br>
<br>
</div> - In the Documentation Table Of Contents page, "Historical<br>
Documents" is listed between "Twisted Core" and "Twisted Lore"<br>
(presumably because of alphabetical order) but this seems<br>
a strange place for it. Could it be moved to the bottom, or an<br>
appendix, or something?<br></blockquote><div><br>They're in alphabetical order. The TOC page is generated dynamically by looking at the file structure of the docs and that's the order file-globbing lists them in. We can fix this manually post-conversion.<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 bottom of every page has a "Download in other formats: Plain<br>
Text" link that doesn't work; presumably scooped up from the Trac<br>
templates. It should be removed (the Sphinx "Show Source" link is<br>
in the right-hand sidebar anyway).<br></blockquote><div><br>Yeah, this is a flaw in the trac theme. Looks like I forgot to remove it.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- When the breadcrumb navigation at the top of the page gets too<br>
long[1], it wraps to a second line, which looks kind of odd<br>
because the nice gradient background image loops. Changing the CSS<br>
background colour to be the same as the bottom of the gradient<br>
image would probably help.<br>
- Firefox's Error Console reports:<br>
- a bogus "%" on line 56 of twistedtrac.css,<br>
- bogus // comments on lines 559, 577, 588, 598 of trac.css (CSS<br>
only allows /* winged comments */)<br>
- Chromium's error console reports:<br>
- A 404 error for "/trac/chrome/common/js/jquery.js"<br>
- A 404 error for "/trac/chrome/common/js/trac.js"<br>
- A 404 error for "/trac/chrome/common/js/search.js"<br>
- A 404 error for "/builds/sphinx-html-15615/_static/dots.gif"<br></blockquote><div><br>Ah! This explains why the search quit working. Not sure why these files are missing, Probably something to do with the custom theme.<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 Twisted.Conch tutorial[1] has a number of things surrounded<br>
with double-backticks like "``Deferred``" or<br>
"``ClientTransport``". I'm not sure if that's deliberate or if<br>
it's markup gone horribly wrong.<br></blockquote><div><br>This is probably due to missing spaces before/after the markup in the rst source. One of those things that will need to be fixed manually. I spent a lot of time trying to fix this in lore2sphinx and when you fix it in one place, it breaks somewhere else. Right now the automated conversion is about as good as it is likely to get with a sane amount of effort.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- On the same page, the text ":api:`<br>
twisted.internet.interface.Transport<br>
< twisted.internet.interface.Transport>`" appears, which also<br>
looks wrong.<br></blockquote><div><br>DItto.<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 Conch code examples (as linked from the code examples page[2])<br>
are sent with a Python mime-type (which Firefox tries to download)<br>
while the .tac files are sent as text/html; this may be an<br>
artifact of the docs being hosted on the buildbot machine rather<br>
than Sphinx, but I think it would be nice if by default they were<br>
displayed in the browser, syntax-highlighted, with an option to<br>
download the original files (much like Trac does).<br></blockquote><div><br>This is a web server configuration thing. The files are actually .py and .tac files (and probably need to remain so, if we ever want to get automated example code tests going).<br>
<br>Maybe we can do some web server magic to get them nicely displayed in the browser, but I see that as a secondary issue for the moment. Anyone should feel free to give a shout if they disagree, though.<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 Twisted Split FAQ[3] has more visible markup:<br>
"twisted.protocols:superscript::ref:`[1]<br>
<core-upgrades-2.0-split-protocols> `". The footnote target is<br>
kind of messed up, too.<br></blockquote><div><br>Another spacing issue.<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 Twisted Split FAQ[3] has a heading "Why are arr the packages<br>
still named twisted.*subproject*?", but it's not obvious whether<br>
the author was trying to use italics (in which case it's<br>
a lore2sphinx bug) or globbing (in which case it's not).<br></blockquote><div><br>Pretty sure it was supposed to be italics. Spacing again. There are ways to make this display properly, but it'll need to be done manually.<br>
<br>Also, this is pretty outdated stuff...we might consider just removing some of this. Or perhaps moving some of it into a more obvious place.<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 Twisted Zope Interfaces FAQ[4] has inline Python source<br>
examples that don't appear to be marked up properly (although this<br>
is possibly a problem with the original Lore source). The answer<br>
to question "How can I update my own code?" is one example.<br></blockquote><div><br>The code bits are marked up this way because of the attributes used on the elements in the Lore source. We can change it easily<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 Banana Protocol Specifications[5], under the heading<br>
"Examples" mentions "the type bytes are marked in bold" but<br>
actually they're surrounded by double-asterisks.<br></blockquote><div><br>Double asterisks are the markup for bold in rst. Another spacing and/or nested inline markup issue.<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 Twisted Coding Standard[6], mentions "the complete test<br>
suite in trunk@HEAD" - and "trunk@HEAD" is converted into<br>
a mailto: link.<br></blockquote><div><br>Huh. I guess that's Sphinx trying to be helpful. Good catch. That'll definitely need fixing.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- Links followed by punctuation seem to leave a space between the<br>
link text and the punctuation. See "test-driven ." and "Test<br>
Standard ." in the Twisted Coding Standard[6], but I've observed<br>
the same problem on multiple pages.<br></blockquote><div><br>This is the spacing issue again, but in reverse. It's relatively easy for lore2sphinx to detect links and add a space at the end, so that's what it does. There's ways to get around this and get rid of the space by escaping it, but it rapidly get mind-boggling, so this is another thing that will need manual fixing.<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 Twisted Coding Standard[6] mentions "If you modify, or write<br>
a new, HOWTO, please read the Lore documentation to learn how to<br>
format the docs"; if there's not already a follow-up ticket for<br>
the lore-sphinx conversion titled "Remove references to Lore from<br>
Twisted's non-Lore-related documentation", there should be, and<br>
this should be in it.<br></blockquote><div><br>There isn't, but there will be. See the transition plan here: <a href="http://twistedsphinx.funsize.net/transition_plan.html">http://twistedsphinx.funsize.net/transition_plan.html</a><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 Twisted Coding Standard[6], under the heading "Modules" says<br>
"Use this template:" and then<br>
"../listings/new_module_template.py".. and *then* includes the<br>
content of said template inline. Presumably it should either link<br>
to it or include it, but not both.<br></blockquote><div><br>It actually is including an external file there (i.e. the contents are not in the rst source, but in the <br>"../listings/new_module_template.py" file. What looks like a link there is actually a sort of heading to <br>
let the reader see where it's coming from. I think this can probably be made clearer with some theme/css changes.<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 HTML Documentation Standard for Twisted[7] has more visible<br>
markup: in the list of allowable markup, most tags are rendered<br>
properly except for "``<tr>``".<br></blockquote><div><br>Missing space after preceding comma. Another manual fix.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- It seems that the HTML Documentation Standard for Twisted[7] is<br>
actually "how to write Lore documentation", despite the name.<br>
Maybe this file should be scheduled for the post-transition purge,<br>
or at least moved to the Lore documentation.<br></blockquote><div><br>It pretty much is "how to write Lore documentation". I think it should probably be moved into the Lore docs, and replaced with the<br>
(yet to be written, but again see the transition plan) planned Twisted Documentation Guide.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- Working from Twisted's Subversion Repository[8] has visible markup<br>
that looks like an attempt to link "the Subversion homepage" under<br>
the heading "Checkout".<br></blockquote><div><br>Missing preceding space again.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- Under the heading "Alternate tree names", the document uses<br>
RIGHT DOUBLE QUOTATION MARK instead of LEFT DOUBLE QUOTATION MARK<br>
in 'directory other than”Twisted” .' Looks like a problem in the<br>
original markup. Also note the space between the LEFT DOUBLE<br>
QUOTATION MARK and the punctuation.<br></blockquote><div><br>The missing preceding space actually is what's causing the quotes to be wrong.<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 same document has more broken links under the "Combinator"<br>
heading.<br></blockquote><div><br>Missing preceding spaces again.<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 same document has broken markup under "Running tests":<br>
"``twisted/protocols/imap4.py``" and later<br>
"``twisted.mail.test.test_imap``".<br>
- The same document has broken markup under "Building docs":<br>
"``doc/development/policy/svn-dev.xhtml`` ," (also trailing space<br>
before punctuation) and<br>
"``doc/development/policy/svn-dev.html`` :" (again).<br>
- The same document has a broken link under "Committing and<br>
Post-commit Hooks", attempting to link the text<br>
"trac-post-commit-hook".<br>
- The same document has broken markup under "Emacs":<br>
"``emacs/twisted-dev.el``".<br>
- The same document has a broken link under "Building Debian<br>
packages", attempting to link th text "stdeb".<br></blockquote><div><br>All bad spacing issues.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<br>
That's probably enough feedback to be getting on with; most of the<br>
problems appear to be from normalising "\n" in Lore docs to "" instead<br>
of " ", and also from adding whitespace after things. It is generally<br>
looking pretty great, though!<br></blockquote><div><br>Yeah, that's pretty much it. As I said above though, if you "fix" it one place, it breaks in another, so I tried to balance things in such a way that the least broken markup appears in the output.<br>
<br>Almost all of the remaining problems will need to be fixed manually.<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<br>
Some extra thoughts:<br>
- The ReviewingDocumentation wiki page has a section called "Editing<br>
man pages" that describes how to turn the nicely-formatted<br>
manpages into Lore input files. Would it be possible to do that as<br>
part of the lore2sphinx run, have the manpages included in the<br>
Sphinx documentation, and from then on generate the manpages from<br>
the .rst files instead of the other way around?<br></blockquote><div><br>Sphinx does have a man page builder now, but I don't think it existed when I was writing lore2sphinx, so I haven't really considered this.<br>
<br>So you're suggesting convert the man pages to Lore format -> use lore2sphinx to convert the resulting Lore docs to rst -> build as part of the Sphinx process, yes?<br><br>I think this is a worthwhile idea, but I'd prefer to leave it until after the main docs are converted (i.e. under a separate ticket). lore2sphinx can be used on just the man files later on if need be, though it would take a little mucking around.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<br>
[1]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
conch/howto/conch_client.html><br>
[2]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
conch/examples/index.html><br>
[3]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
core/upgrades/2.0/split.html><br>
[4]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
core/upgrades/2.0/components.html><br>
[5]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
core/specifications/banana.html><br>
[6]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
core/development/policy/coding-standard.html><br>
[7]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
core/development/policy/doc-standard.html><br>
[8]: <<a href="http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/" target="_blank">http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/</a><br>
core/development/policy/svn-dev.html><br>
<div><div></div><div class="h5"><br></div></div></blockquote></div><br>Thanks for the fantastic (and nicely detailed) feedback, Tim!<br><br>Please take a look at the transition plan. In a few days (maybe sooner), I should have the base docs in a branch, and the "chunk tickets" referenced in the transition plan created. This is pretty much _exactly_ what I'd like to see in those "chunk tickets". Hopefully you haven't already burned up your brain staring at markup issues. :) We could really use this kind of help throughout the process. <br>
<br>Kevin Horn<br>