On Thu, Mar 4, 2010 at 5:49 PM, Kevin Horn <kevin.h...@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
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
