Making Multi-Level Anchors Work With for Sphinx

One of the issues I’ve come across when using Sphinx (awesome application) for writing documentation is that the table of contents disappear when using the singlefile format (which generates the documentation as one large page instead of having to click through to other files).

Luckily Matteo Franchin had the same issue, and created a small extension for Sphinx that allows you to add a TOC to SingleHTML builders as well! The problem I discovered after a while is that it ends up adding redundante HTML anchors for each level when resolving the TOC, where it ends up generating #html#anchors like that. Which doesn’t work.

I solved the issue (.. for my simple case, this is still a hack) by adding regular expression that removes any HTML anchors that are followed by another HTML-anchor (and could very possibly eat a lot more in edge cases, but hey, it works for me!).

rendered_toctree = re.sub(r'(#[^ "]+)#', '#', rendered_toctree);

The lines around line 59 should then look like:

            rendered_toctree = builder._get_local_toctree(docname, **kwargs)
            rendered_toctree = re.sub(r'(#[^ "]+)#', '#', rendered_toctree);
            node['content'] = rendered_toctree

Rounding Up The Remaining Database Posts

To finally be able to close my now-ready-to-be-archived Firefox-window, I’m rounding up the three other posts I were going to post about in one single batch here:

Ulf Wendel has a post up about PDO_MYSQLND: The new features of PDO_MYSQL in PHP 5.3. Besides being yet another introduction to how MYSQLND differs from the regular libmysqlclient, Ulf writes in detail about how mysqlnd brings other speedups to PDO in general, by allowing the drivers to return zvals directly. This allows the driver to return data without requiring an explicit copy by the overlying architecture. Interesting stuff and well worth a read for anyone, regardless if you actually know what a zval is.

Nicklas Westerlund has a post about MySQL Back to Basics: Analyze, Check, Optimize, and Repair on the pythian blog, featuring a overview of the useful – and abused – methods of rescuing and keeping your data intact. Do regular and good backups. It’s as easy as that. This might however help when you’re in a hurry or needs to fix a corruption that has occured. Read it.

The last item on today’s list is Sphinx – a free open-source full-text search engine. Sphinx uses it’s own indexing and retrieval system, while Solr is built on top of Lucene. Haven’t had much time to play with it yet, but it’s worth checking out. A native PHP module has also popped up (and that’s where I read about it just now), so if you need a fast and native PHP interface to a full search engine without blowing the big bucks, this may be what you’re looking for.