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

[Drew Smathers]

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.
> 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!
>
>
>
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
example:

http://twistedsphinx.funsize.net/projects/web/howto/web-in-60/asynchronous.html

... which is missing syntax highlighting on code examples and the code
examples are also truncated.

-Drew
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20100305/e8ca6370/attachment.htm