Notes On Sphinx Themes For RestructuredText Based Documentation

Abstract:Notes on Sphinx Themes and customization
Author:Thava Alagu
Date:25 Jan 2013


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:

  • Run sphinx-quickstart to generate a build template.

  • Change index.rst file to include yourfile.rst

  • Customize the following files:

    $ ls _static/ _templates/
    basic_screenshot.png        default.css             logo.png

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 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
$ pip install $themes

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

# basicstrap / bizstyle / dotted / htmlslide / impressjs / s6 / trstyle
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:

  • impressjs: For extreme visual effects like rotating and zooming.
  • htmlslide
  • S6

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


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