Skip to content

A Google Code Sphinx Theme

October 21, 2008

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…

…and the second shows some search results using the Sphinx search engine:


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:

svn propset -R svn:mime-type text/css `find build/html/ -name .svn
  -type f -prune -o -name *.css`
svn propset -R svn:mime-type text/javascript `find build/html/
  -name .svn -type f -prune -o -name *.js`
svn propset -R svn:mime-type image/x-png `find build/html/
  -name .svn -type f -prune -o -name *.png`
svn propset -R svn:mime-type text/html `find build/html/ -name .svn
  -type f -prune -o -name *.html`

That’s it. Now “publish” your documentation by running svn commit… ,-)

To view your documentation point your browser to http://<YOUR_PROJECT&gt;.googlecode.com/svn/<DOCROOT>/build/html/index.html.

6 Comments
  1. coredump permalink
    November 9, 2008 2:58 am

    This is brilliant. Just did it and it works perfectly.

    I was thinking in making a builder or a template that spits wiki markup but your solution is way more cleaner!

    A+

  2. coredump permalink
    November 9, 2008 6:52 am

    BTW, where do I change in the CSS for the class=pre to be a little bigger like in function references and stuff.

  3. andi permalink
    November 9, 2008 7:13 am

    There’s a CSS rule for the PRE tag in custom.css. Isn’t it what you’re looking for?

  4. mikeal permalink
    March 5, 2009 4:37 pm

    in zsh you need to put the *.css and such in quotes “*.css”

  5. Denis permalink
    October 2, 2009 12:08 pm

    When I visit this link http://python-pocdock.googlecode.com/svn/trunk/docs/build/html/index.html I get a barely visible page on a very dark background. Apparently, it cannot load one of the css files.

    • October 2, 2009 12:16 pm

      The style doesn’t work anymore since Google changed there CSS inbetween. It might just a few changes, but I haven’t looked into this for a while now.

Comments are closed.

%d bloggers like this: