Notes On Sphinx Themes For RestructuredText Based Documentation

Author: Thava Alagu
Date: 25 Jan 2013

Abstract

Notes on Sphinx Themes and customization

Contents

References

Introduction

Sphinx document generation tool was originally created for Python documentation. However it has grown to be very powerful general purpose documentation system based on RestructuredText.

Sphinx Theming is highly customizable. This document describes the resources and procedures about how to get and customize these themes.

I use this extensively to consolidate my own technical notes written using RestructuredText. Sphinx generates a nice consolidated documentation to view them.

Sphinx Example Site Customization Tutorial

You may want to look at Sphinx example site customization Tutorial first for an example.

Basically this involves following steps:

This gives some fundamental ideas about customization. All these above changes are applied on top of the basic built-in theme that is in effect. You can change that theme too if you like.

Built-in Themes

To see the list of built-in themes available, look inside your Python installation:

$ ls lib/python2.7/*-packages/sphinx/themes/

agogo/    basic/      default/      epub/  haiku/  nature/  pyramid/
scrolls/  sphinxdoc/  traditional/

See Sphinx Theming to preview their look and feel. Built-in themes come with certain amount of customization options. You can specify following in your conf.py file as an example:

html_theme = "default"
html_theme_options = {
    "rightsidebar": "true",
    "stickysidebar": "true",
    "relbarbgcolor": "black"
}

If this is more than what you need, you can stop here. If you want further customization, read on.

Installing Additional Themes

Go to Python Package Index and search for Sphinx theme or Sphinx template. Here are some of the themes I chose to install from that list:

$ themes="  sphinxjp.themes.basicstrap
            sphinxjp.themes.bizstyle
            sphinxjp.themes.dotted
            sphinxjp.themes.htmlslide
            sphinxjp.themes.impressjs
            sphinxjp.themes.s6
            sphinxjp.themes.trstyle
            "
$ pip install $themes

To preview these themes, usually you just configure your conf.py, like below

# basicstrap / bizstyle / dotted / htmlslide / impressjs / s6 / trstyle
html_theme=basicstrap
html_theme_options = {}

$ make html

Refer to the theme specific documentation from Python Package Index package page for more information.

Generating Slides using RST

It is very handy to be able to generate presentation slides by writing RestructuredText text. There are few such extensions among the earlier mentioned sphinxjp.* themes:

The impressjs support is very impressive. You can look at the impressjs sphinx extension demo page. The source for the above demo is here

Conclusion

After comparing many themes, I found the default theme is the best after tweaking for my taste: I enabled the rightsidebar instead of left. The next best built-in theme I liked is Pyramid with clean look. Next, among sphinxjp themes I liked bizstyle theme for general use. However, these are very subjective to one's tastes.

There are also numerous other Sphinx themes-- every major project such as django provides it's own customized theme. It is easy to get inspiration by looking at some of them and just pick something you like as the base and customize it further if needed.

Often, by tweaking some options (like just increasing the fontsize), you can achieve dramatic improvements to suit your taste.

Source Document

This document has been written using RestructuredText and converted to HTML using rst2html command.

See the document source text