On Thu, Mar 4, 2010 at 5:49 PM, Kevin Horn <span dir="ltr"><<a href="mailto:kevin.horn@gmail.com">kevin.horn@gmail.com</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<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" target="_blank">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" target="_blank">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" target="_blank">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>
<br></blockquote></div><br>
<div>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:</div><div><br></div><div><a href="http://twistedsphinx.funsize.net/projects/web/howto/web-in-60/asynchronous.html">http://twistedsphinx.funsize.net/projects/web/howto/web-in-60/asynchronous.html</a></div>
<div><br></div><div>... which is missing syntax highlighting on code examples and the code examples are also truncated.</div><div><br></div><div>-Drew</div><div><br></div><div><br></div>