[Twisted-Python] Lore to Sphinx Conversion Progress Report 6
drew.smathers at gmail.com
Fri Mar 5 10:30:44 EST 2010
On Thu, Mar 4, 2010 at 5:49 PM, Kevin Horn <kevin.horn at gmail.com> wrote:
> 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.
> fixes a few minor display bugs and should make pages validate properly.
> - inline markup will now include child contents. This causes rst not to
> 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
> very important, so we just return the contents of the tag without any
> markup. If we feel the need to put citation markup back into the docs we
> do that post-transition.
> - Glyph also found an easy way to improve the CSS of the theme somewhat.
> 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
> tags into something like: :api:`path.to.documented object <label>`, and
> 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
> First, the way pydoctor generates links is deceptively simple.
> If you look up a module, like "twisted.internet.defer", the link looks
> If you look up a class, like "twisted.internet.defer.Deferred" for
> the link looks like this:
> 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 we'll need to do some checking on either the api docs or on twisted
> 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
> a docutils role function. I'm sure this is just a matter of finding an
> 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!
How can I filter for tickets related to lore2sphinx transition in trac?
I've noticed a few documents that don't seem properly converted. Here's an
... which is missing syntax highlighting on code examples and the code
examples are also truncated.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Twisted-Python