[Twisted-Python] Lore to Sphinx Conversion Progress Report 6

Tim Allen screwtape at froup.com
Sat Jul 10 03:40:59 EDT 2010

On Sat, Jul 10, 2010 at 02:58:40AM -0000, exarkun at twistedmatrix.com wrote:
> At last I've got a buildbot set up generating the sphinx docs.  The 
> build results can be seen here:
>   http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/
> (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[1], 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[1] 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>`" appears, which also
      looks wrong.
    - The Conch code examples (as linked from the code examples page[2])
      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[3] has more visible markup:
      <core-upgrades-2.0-split-protocols> `". The footnote target is
      kind of messed up, too.
    - The Twisted Split FAQ[3] 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[4] 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[5], under the heading
      "Examples" mentions "the type bytes are marked in bold" but
      actually they're surrounded by double-asterisks.
    - The Twisted Coding Standard[6], mentions "the complete test
      suite in trunk at HEAD" - and "trunk at 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[6], but I've observed
      the same problem on multiple pages.
    - The Twisted Coding Standard[6] 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[6], 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[7] 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[7] 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[8] 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
      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"
    - The same document has broken markup under "Running tests":
      "``twisted/protocols/imap4.py``" and later
    - 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
    - The same document has broken markup under "Emacs":
    - 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?

[1]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[2]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[3]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[4]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[5]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[6]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[7]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
[8]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/

More information about the Twisted-Python mailing list