Sphinx themes and configuration file

In this post, I describe the procedure to create a new CSS theme in Sphinx, which is a tool dedicated to software documentation (and documentation in general). For an example of HTML pages generated automatically with Sphinx, you can look at my Spectrum software in Python pages.

When you first created your Sphinx project, you probably used the executable provided by Sphinx and typed:


sphinx-quickstart


This executable created for you a configuration file (generally called conf.py). By default, a theme is selected for you.
If you inspect the file, you should find somewhere these variables (possibly commented)

# html_theme =
# html_theme_options = {}
# html_theme_path =


That’s where you can specify a new theme. First, you need to define a directory where to add new themes. For this exercice, we can set it to /home/user/themes/software. Second, we choose a new theme’s name: ‘software’ . Third, you set
this new path and themes’s name in the configuration file:


html_theme = 'software'
html_theme_options = {}
html_theme_path = '/home/user/themes'


Finally, you need to create the theme. To start a new theme, the best is to copy an existing one from Sphinx (usually in lib/pythonX.X/site-packages/Sphinx/sphinx/themes). Copy it to your themes directory.

Now it is time to edit the file theme.conf and adapt it to your needs by changing the section [theme] to agree with the CSS file you want to use.

Please follow and like us: