A Google Code Sphinx Theme
The wiki feature on Google Code is a great feature to provide documentation for a project. In my opinion it has to big benefits: You can version your documentation and (thanks to the wiki markup) it’s easy to maintain.
But on the other hand writing your projects documentation using the wiki has some limitations. Especially when you know Sphinx, the documentation generator used by Python, you will miss some features like Python-specific markup, automagic index generation, sections and chapters and last but ot least the power of restructured text ;-)
Unfortunately Google Code Hosting offers no official way to serve static files. So if you want to use Sphinx for your documentation, you need to publish it somewhere else and put a link on your project page. Wouldn’t it be great to use Sphinx and integrate it with everything else?
So let’s do it, but first off here’s how it looks like (visit this project page to see it in action):
And two other screenshots. The first one shows an index…
Here’s how to use this theme for your project and how to “publish” it on Google Code. Read the Sphinx documentation if you don’t know anything about Sphinx yet. To make this work, your documentation files and the generated HTML output must live somewhere in your Subversion repository.
The theme consists of three files: Grab the CSS from here and place it in the directory for static files (usually DOCROOT/source/.static where DOCROOT is the root directory of your Sphinx documentation), then grab the two templates (layout.html, search.html) and place them in the templates folder (DOCROOT/source/.templates).
Now open the configuration file of your documentation (conf.py) and make sure it has this line html_file_suffix = ‘.html’. It’s required to build the correct URL for search results.
The layout template has some configuration options. Open layout.html in your favorite editor and customize them for your needs:
gcprj –> set this to match your project name (the one in the URL…).
gcusedownloads –> 1 = show “Downloads” tab, 0 = don’t show it
gcusewiki –> 1 = show “Wiki” tab, 0 = don’t show it
gcuseissues –> 1 = show “Issues” tab, 0 = don’t show it
gcusespurce –> 1 = show “Source” tab, 0 = don’t show it
Then build the HTML version of your documentation by running make html. Make sure that all generated files are under version control (e.g. by running svn status build/html) as we will deliver all content straight out of the repository… ,-)
Finally you need to set the correct mime types for all generated files. Otherwise they’re delivered as plain text which is not very useful in our case. You can easily set the correct SVN properties by running the following commands:
That’s it. Now “publish” your documentation by running svn commit… ,-)
To view your documentation point your browser to http://<YOUR_PROJECT>.googlecode.com/svn/<DOCROOT>/build/html/index.html.