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