[Twisted-Python] Lore to Sphinx Conversion Progress Report 6
Tim Allen
screwtape at froup.com
Sat Jul 10 01:40:59 MDT 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
< 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:
"twisted.protocols:superscript::ref:`[1]
<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
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?
[1]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
conch/howto/conch_client.html>
[2]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
conch/examples/index.html>
[3]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
core/upgrades/2.0/split.html>
[4]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
core/upgrades/2.0/components.html>
[5]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
core/specifications/banana.html>
[6]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
core/development/policy/coding-standard.html>
[7]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
core/development/policy/doc-standard.html>
[8]: <http://buildbot.twistedmatrix.com/builds/sphinx-html-15615/projects/
core/development/policy/svn-dev.html>
More information about the Twisted-Python
mailing list