sphinx :: adding a new theme

Sphinx (http://sphinx.pocoo.org/) has made our internal documentation effort go a lot smoother, and the autodoc extension has provided much needed motivation for writing useful docstrings.

For those unfamiliar with autodoc, a simple declaration in your documentation file:

.. automodule:: test.sphinxtest

will automatically document your module, pulling in docstrings automatically:

Sphinx with autodoc output (default theme).

At first glance that’s nice, but after having used it for a while it becomes clear that your eyes are drawn away from the content and onto the “packaging”, like the headers/TOC/etc. It is also difficult to tell which level you’re at since all headers start flush left.

The choice of fonts for describing classes also seems a bit unusual — at least for first time readers:

Sphinx classdef (default theme)

There are other themes to choose from, but if you’re going to customize you might as well create your own theme — especially since it’s really easy.

I’ll use our dktheme as an example, the finished product looks like this:

Sphinx with dktheme

To start, create a folder (dktheme) to hold your theme files. I chose to put it in the documentation folder. Change your conf.py file to reflect the new folder:

html_theme = 'dktheme'
html_theme_path = ['.']

Create a theme.conf file in the folder and provide a few basic configuration settings:

inherit = default
stylesheet = dktheme.css
pygments_style = sphinx

inherit declares which theme you want to use as a base (they exist in site-packages/sphinx/themes). pygments_style defines which syntax highlighting color scheme to use.

Create a directory dktheme/static, and put a file named dktheme.css_t in it. Notice the _t suffix. This file corresponds to the stylesheet setting in the dktheme/theme.conf file.

Define your own css rules inside dktheme.css_t, but begin by importing the css file of the theme you’re inheriting from:

@import url("default.css");

Firebug/Webdeveloper/etc. are useful for finding the correct selectors to override:

@import url("default.css");

html, body, h1, h2, h3, h4, h5, h6 {
  font-family: 'Ubuntu', 'Trebuchet MS', sans-serif !important;

.footer a,
.related ul,
.related ul li a  {
    background-color: #c0c0cf !important;
    color:#808080 !important;

.related ul {
  max-width:900px; margin-left:250px !important; font-size:smaller
.related ul a {  background-color: transparent !important;}

.body {
  -moz-box-shadow:0px 0px 12px #666;
  -webkit-box-shadow:0px 0px 12px #666;
  box-shadow:0px 0px 12px #666;
  margin:15px 25px 15px 0px;
  margin:0px 25px 0px 0px;
  border:9px solid white;

.sphinxsidebar a,
.sphinxsidebar h3,
.sphinxsidebar h4,
.sphinxsidebar h5 { color:#555 !important }

.sphinxsidebar .searchtip { color:black; }

.body h1,
.body h2,
.body h3,
.body h4,
.body h5,
.body h6 {
  margin-left: 0px !important;
  margin-right: 0px !important;
  padding-left:0 !important;
  background-color: white !important;

.body h1 { padding-top:17px !important; }

.section .section { margin-left:14px }

.class big { font-size:85%; }
.class em { font-size:85%; }

.class .property,
.class .descclassname,
.class .descname { font-size:100%; line-height:100%; }

.class .property {

.descclassname { font-size:100% !important; font-family: Tahoma; }
.descname { color:#041F3F; font-size:100% !important; font-family: Tahoma; }

dl.method::before {
    float:left; margin-right:0.5ex;
    font-weight:bold; color:#222;

dl.attribute::before {
    float:left; margin-right:0.5ex;

dd > p { font-size:85%; }

I’ve used ::before rules to e.g. insert the word def before method definitions.

At the top I’ve listed the preferred font as being Ubuntu, which is a very clean font that Google has made available as a webfont (www.google.com/webfonts).

To use the Ubuntu web font, you’ll need to add a link to its css file in the <head> section of your html.  To accomplish this, you’ll need to add a final file to your theme, dktheme/layout.html, with the following content:

{% extends "default/layout.html" %}

{% block extrahead %}
<link href="http://fonts.googleapis.com/css?family=Ubuntu:300,300italic,regular,italic,500,500italic,bold,bolditalic" rel="stylesheet" type="text/css">
{% endblock %}

What this does should be obvious to anyone familiar with Django templates (although these are Jinja templates).

I’m not a graphical designer, but to my development eyes the documentation is much easier to use with the new theme 🙂

This entry was posted in Uncategorized and tagged , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *