Sphinx Themes
+++++++++++++

:Posted: 2009-07-30 16:58
:Tags: Pylons

`Sphinx <http://sphinx.pocoo.org/>`_ 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
<http://pylonsbook.com/en/1.0/documentation.html#introducing-sphinx>`_ in `my
book on Pylons <http://pylonsbook.com>`_ 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
<http://sphinx.pocoo.org/theming.html>`_. 

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 <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
<../../work/code/commandtool/0.3.0/index.html>`_ page, all generated with Sphinx.