[Twisted-Python] Lore to Sphinx Conversion Progress Report 6
Kevin Horn
kevin.horn at gmail.com
Thu Mar 4 17:49:57 EST 2010
It's been a while, I know you were all waiting with baited breath...
First a few fixes:
- Thanks to Tim Allen and Steve Steiner, several theme issues were fixed.
This
fixes a few minor display bugs and should make pages validate properly.
- inline markup will now include child contents. This causes rst not to
display
properly in cases of "nested inline markup", but should make it easier to
manually fix these places later
- :download: links are now generated for non-rst files ending in .py (most
of the
examples), as welll as .tac and .sql files
- toc entries which end in a "/" character now have "index appended to them
in the ReST output, which fixes a few issues where the built-Sphinx docs
would end up with broken navigation links.
A couple of issues were also fixed at the PyCon sprints:
- <cite> tags are now handled...sort of. According to Glyph, these aren't
really
very important, so we just return the contents of the tag without any
special
markup. If we feel the need to put citation markup back into the docs we
can
do that post-transition.
- Glyph also found an easy way to improve the CSS of the theme somewhat.
The
issue where the sidebar drops below the main content should now be less of
a
problem, though it's not gone entirely.
- Glyph and I also discussed a few different ways to handle links to the API
docs
and agreed on a way forward. Basically, well change the <code
class='API'>
tags into something like: :api:`path.to.documented object <label>`, and
then
create a docutils extension to convert that into a link. The beginnings
of this
are in the hg repos, but it looks like it won't be quite as simple as we
thought.
First, the way pydoctor generates links is deceptively simple.
If you look up a module, like "twisted.internet.defer", the link looks
like
this:
http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.html
If you look up a class, like "twisted.internet.defer.Deferred" for
example,
the link looks like this:
http://twistedmatrix.com/documents/current/api/twisted.internet.defer.Deferred.html
Pretty simple right? But if you look up a function or method like
"twisted.internet.defer.Deferred.callback", the link has an anchor, like
so:
http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html#addCallback
So we'll need to do some checking on either the api docs or on twisted
itself
to determine what sort of object is being linked to. Shouldn't be
super-difficult, just haven't had time yet.
Second, I haven't yet figured out how to access the Sphinx config object
from
a docutils role function. I'm sure this is just a matter of finding an
example
or getting an answer from the mailing list, but I just haven't gotten to
it yet.
I think the API links are the only major issue still remaining until we
start doing
the conversion, so once this issue is handled, I'll probably file a ticket
and create
a branch in SVN for the conversion.
If anyone has any docs tickets open, now is the time to get them fixed!
And if anyone has some great ideas about how to organize the new docs in the
repository, I'd love to hear them.
As always, converted docs are here:
http://twistedsphinx.funsize.net/
The lore2Sphinx Hg repos is here:
http://bitbucket.org/khorn/lore2sphinx/
Comments, ideas, patches and pull requests gratefully accepted (or at least
discussed).
Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20100304/03703c78/attachment.htm
More information about the Twisted-Python
mailing list