Home Blog CV Projects Patterns Notes Book Colophon Search

Sphinx Themes

30 Jul, 2009

Sphinx is an excellent documentation tool written by Georg Brandl. It takes reStructuredText code as well as a load of custom markup and generates HTML or PDF pages from it.

I wrote a chapter about Sphinx in my book on Pylons and it is used to generate all the Python documentation.

I tend to use Sphinx for pretty much every project I start and although the default themes are very nice, I'd like Sphinx better integrated into my sites. This turns out to be very easy because Sphinx supports different themes.

My sites are all written using static DreamWeaver-style templates managed through a command line tool I wrote called SiteTool. To integreate Sphinx I needed a theme which replaced the pretty HTML with DreamWeaver-style comments and stripped out all the navigation components so that the navigation would be consistent with the rest of the site, not specific to the documentation. This turns out to be very easy to do.

Install Sphinx
Copy the basic directory within env/lib/python2.5/site-packages/Sphinx-0.6.1-py2.5.egg/sphinx/themes/ to one called dwt_jimmyg.
Edit the layout.html file to add in the DreamWeaver markup and strip out the side bar, footer and navigation

My changes are pretty crude but here's the changed zip if you are interested:

Download dwt_jimmyg.zip

Tip

All my Sphinx files are three levels away from the site root so all the markup contains ../../../../ components to link to the templates and library items. If you are putting them in a different place you'll need to change them accordingly. Also, bear in mind that unless the Sphinx-generated markup is inside one of the editable regions of the template, the markup will be stripped out when the page gets updated. Make sure you have the JavaScript files needed for the search included in the head editable region for example.

Now that you have the new theme installed you just need to edit the conf.py file for your Sphinx project.

Change this line:

html_theme = 'default'

to this:

html_theme = 'basic'

Now when you run make html your files will be generated with DreamWeaver markup and when you put those files in place and update them, the template and library items will be correctly re-applied.

You can see the result of this on my CommandTool page, all generated with Sphinx.