On Sat, Jul 10, 2010 at 02:58:40AM -0000, email@example.com wrote:
At last I've got a buildbot set up generating the sphinx docs. The build results can be seen here:
(or with a different revision number for different revisions; the containing directory is browseable).
It would be great if everyone could go look around and report any problems you see.
- In the Documentation Table Of Contents page, "Historical Documents" is listed between "Twisted Core" and "Twisted Lore" (presumably because of alphabetical order) but this seems a strange place for it. Could it be moved to the bottom, or an appendix, or something? - The bottom of every page has a "Download in other formats: Plain Text" link that doesn't work; presumably scooped up from the Trac templates. It should be removed (the Sphinx "Show Source" link is in the right-hand sidebar anyway). - When the breadcrumb navigation at the top of the page gets too long, it wraps to a second line, which looks kind of odd because the nice gradient background image loops. Changing the CSS background colour to be the same as the bottom of the gradient image would probably help. - Firefox's Error Console reports: - a bogus "%" on line 56 of twistedtrac.css, - bogus // comments on lines 559, 577, 588, 598 of trac.css (CSS only allows /* winged comments */) - Chromium's error console reports: - A 404 error for "/trac/chrome/common/js/jquery.js" - A 404 error for "/trac/chrome/common/js/trac.js" - A 404 error for "/trac/chrome/common/js/search.js" - A 404 error for "/builds/sphinx-html-15615/_static/dots.gif" - The Twisted.Conch tutorial has a number of things surrounded with double-backticks like "``Deferred``" or "``ClientTransport``". I'm not sure if that's deliberate or if it's markup gone horribly wrong. - On the same page, the text ":api:` twisted.internet.interface.Transport < twisted.internet.interface.Transport>`" appears, which also looks wrong. - The Conch code examples (as linked from the code examples page) are sent with a Python mime-type (which Firefox tries to download) while the .tac files are sent as text/html; this may be an artifact of the docs being hosted on the buildbot machine rather than Sphinx, but I think it would be nice if by default they were displayed in the browser, syntax-highlighted, with an option to download the original files (much like Trac does). - The Twisted Split FAQ has more visible markup: "twisted.protocols:superscript::ref:` <core-upgrades-2.0-split-protocols> `". The footnote target is kind of messed up, too. - The Twisted Split FAQ has a heading "Why are arr the packages still named twisted.*subproject*?", but it's not obvious whether the author was trying to use italics (in which case it's a lore2sphinx bug) or globbing (in which case it's not). - The Twisted Zope Interfaces FAQ has inline Python source examples that don't appear to be marked up properly (although this is possibly a problem with the original Lore source). The answer to question "How can I update my own code?" is one example. - The Banana Protocol Specifications, under the heading "Examples" mentions "the type bytes are marked in bold" but actually they're surrounded by double-asterisks. - The Twisted Coding Standard, mentions "the complete test suite in trunk@HEAD" - and "trunk@HEAD" is converted into a mailto: link. - Links followed by punctuation seem to leave a space between the link text and the punctuation. See "test-driven ." and "Test Standard ." in the Twisted Coding Standard, but I've observed the same problem on multiple pages. - The Twisted Coding Standard mentions "If you modify, or write a new, HOWTO, please read the Lore documentation to learn how to format the docs"; if there's not already a follow-up ticket for the lore-sphinx conversion titled "Remove references to Lore from Twisted's non-Lore-related documentation", there should be, and this should be in it. - The Twisted Coding Standard, under the heading "Modules" says "Use this template:" and then "../listings/new_module_template.py".. and *then* includes the content of said template inline. Presumably it should either link to it or include it, but not both. - The HTML Documentation Standard for Twisted has more visible markup: in the list of allowable markup, most tags are rendered properly except for "``<tr>``". - It seems that the HTML Documentation Standard for Twisted is actually "how to write Lore documentation", despite the name. Maybe this file should be scheduled for the post-transition purge, or at least moved to the Lore documentation. - Working from Twisted's Subversion Repository has visible markup that looks like an attempt to link "the Subversion homepage" under the heading "Checkout". - Under the heading "Alternate tree names", the document uses RIGHT DOUBLE QUOTATION MARK instead of LEFT DOUBLE QUOTATION MARK in 'directory other than”Twisted” .' Looks like a problem in the original markup. Also note the space between the LEFT DOUBLE QUOTATION MARK and the punctuation. - The same document has more broken links under the "Combinator" heading. - The same document has broken markup under "Running tests": "``twisted/protocols/imap4.py``" and later "``twisted.mail.test.test_imap``". - The same document has broken markup under "Building docs": "``doc/development/policy/svn-dev.xhtml`` ," (also trailing space before punctuation) and "``doc/development/policy/svn-dev.html`` :" (again). - The same document has a broken link under "Committing and Post-commit Hooks", attempting to link the text "trac-post-commit-hook". - The same document has broken markup under "Emacs": "``emacs/twisted-dev.el``". - The same document has a broken link under "Building Debian packages", attempting to link th text "stdeb".
That's probably enough feedback to be getting on with; most of the problems appear to be from normalising "\n" in Lore docs to "" instead of " ", and also from adding whitespace after things. It is generally looking pretty great, though!
Some extra thoughts: - The ReviewingDocumentation wiki page has a section called "Editing man pages" that describes how to turn the nicely-formatted manpages into Lore input files. Would it be possible to do that as part of the lore2sphinx run, have the manpages included in the Sphinx documentation, and from then on generate the manpages from the .rst files instead of the other way around?
: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ conch/howto/conch_client.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ conch/examples/index.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ core/upgrades/2.0/split.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ core/upgrades/2.0/components.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ core/specifications/banana.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ core/development/policy/coding-standard.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ core/development/policy/doc-standard.html> : <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/ core/development/policy/svn-dev.html>