<div class="gmail_quote">On Fri, Mar 5, 2010 at 9:30 AM, Drew Smathers <span dir="ltr"><<a href="mailto:drew.smathers@gmail.com">drew.smathers@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div><div></div><div class="h5">On Thu, Mar 4, 2010 at 5:49 PM, Kevin Horn <span dir="ltr"><<a href="mailto:kevin.horn@gmail.com" target="_blank">kevin.horn@gmail.com</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; 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></div><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" target="_blank">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><font color="#888888"><div>-Drew</div></font><br></blockquote></div><br>As far as I know, there aren't any tickets in Trac yet. I was planning on making some (or asking others to do so) once a "master ticket" and a branch are created.<br>
<br>As for the specific issue you linked to, the ReST markup is similar to that on other pages, but it looks like Sphinx isn't recognizing the code samples as Python for some reason. I'll look into this later on.<br>
<br>Kevin Horn<br>