Sphinx Themes#

Sphinx theme is skin that changes the appearance of HTML version of the documentation. It contains HTML templates, CSS stylesheets, and static files like images, favicon, fonts, etc.

What is Sphinx theme?#

Sphinx theme is physically represented as a folder or ZIP file. The name of the folder or file (without ZIP suffix) becomes the name of the theme. In both cases, it must contain theme.conf file to be correctly recognized as Sphinx theme. The other files, like HTML, CSS, and JS, are optional.

The theme is independent of the project. Once build, you can distribute the theme and use it across many Sphinx projects.

Resulting HTML code comes from templates. Templates are .html files written with Jinja2 templating language. During processing a template, Sphinx injects actual document body, document title, table of contents, etc. The most important templates are called layout.html (main template) and page.html (customizing document body appearance).

The rest of the theme are static assets files in static folder - images, styles, JavaScript, whatever your theme needs.

my_theme/
    static/
        img/
            favicon.ico
            logo.png
        css/
            main.css
        js/
            main.js
    theme.conf
    layout.html

What you can and can’t change#

Before continuing, it is essential to clearly understand what your theme can and can’t change.

Sphinx takes document source files and renders them as HTML. You can’t change markup generated from document. For example, this section and first two paragraphs written in as

*****************************
What you can and can't change
*****************************

Before continuing, it is important to clearly understand what your theme
can and can't change.

Sphinx takes document source files and render them as HTML. You **can't
change markup generated from document**. For example, this section and
first two paragraphs written in |rst| as

will produce the following HTML:

<div class="section" id="what-you-can-and-can-t-change">
    <h2>What you can and can’t change
        <a class="headerlink" href="#what-you-can-and-can-t-change"
           title="Permalink to this headline">¶
       </a></h2>
    <p>Before continuing, it is important to clearly understand what your
        theme can and can’t change.</p>
    <p>Sphinx takes document source files and render them as HTML. You
        <strong>can’t change markup generated from document</strong>. For
        example, this section and first two paragraphs written in
        reStructuredText as</p>

Many themes often show global (project) or local (current document only) table of contents (ToC), e.g. in the sidebar. You also can’t modify HTML markup of the global and table of contents. Sphinx generates an unordered list (<ul><li>) for both types of ToC.

Hopefully, the HTML code rest of the page is up to the theme, i.e. you can develop any web page HTML code except document body, global ToC and local ToC.

Every theme looks different, but, for example, for this website theme document body is this (the rest of the page is static or prepared in the theme):

theme.conf#

Every theme must contain theme.conf. It is a text file with INI-like syntax that sets basic theme information. It must contain [theme] section, and may contain [options] section.

[theme] typically looks like this example:

[theme]
inherit = basic
stylesheet = css/main.css
pygments_style = default

where

inherit – the only required option in [theme] section. inherit is the of theme used to lookup missing Jinja templates. Also, theme options and static files are inherited from base theme. It is useful to inherit from another theme. Almost all themes inherit from basic theme. If you don’t want to inherit specify none.
stylesheet – the path to main theme’s stylesheet. The path is relative to the theme static folder. layout.html template use the value to construct <link rel="stylesheet" href="<path-to-stylesheet>"> in HTML <head>. User’s can override this value with conf.py html_theme option.
pygments_style – Pygments is library used by Sphinx to deliver syntax highlighted code examples <code-block-highlighting>. Most light themes uses “default” style. But find the most matching style in Pygments demo - paste a few lines of code, and try different builtin styles. User’s can override this value with conf.py html_pygments_style option.

Static files#

Theme can’t exist without its static file (also called static assets) - files used as-is without dynamic parts.

In the theme source, they are expected under static/ folder. In the output, they all end-up under _static/ folder.

Theme static files may be overwritten by user static files defined in conf.py html_static_path list. It allows easy customization of existing themes.

Project-specific themes#

As said above, the theme is either folder or ZIP file with theme.conf, HTML templates and static files.

The themes intended for a wide audience can be distributed as Python packages. An example of such theme is this website theme installable just by pip3 install sphinx-documatt-theme command.

If you don’t need to share it, you may keep the theme as folder in Sphinx document sources. This is the case of most company documentation - the theme of documentation needs to match to the design of the main company website. It is unlikely or undesired to share the theme.

Good place for such project-specific themes is _themes/ in the directory with conf.py, and set html_theme = "mytheme" and html_theme_path = ["_themes"] in your conf.py:

_themes/
    mytheme/
        static/
            css/
                main.css
        theme.conf
        layout.html
_static/
conf.py
index.rst
second.rst
third.rst

Using a theme#

Using depends on how did you obtain a theme.

Builtin themes that comes with Sphinx are easiest to use. Just set theme name in conf.py html_theme option.
```
html_theme = "alabaster"
```
If a theme comes as folder/ZIP, add the path to it to the conf.py html_theme_path option. The option is the list of paths that Sphinx will use to lookup first.
```
html_theme = "mytheme"
html_theme_path = ["_themes"]
```
If html_theme_path option is not set, Sphinx will search in installed Python packages. If you, e.g. installed sphinx_documatt_theme with pip3 install sphinx_documatt_theme, just set
```
html_theme = "sphinx_documatt_theme"
```

Theme options#

Themes may be configurable with theme options. Theme options are usually used for setting font family, hiding logo, hiding prev/next buttons, etc.

Theme author needs to define default values in theme.conf’s [options] section. For example:

[theme]
...

[options]
motto = Write and read beautiful books and documentation.
show_prev_next = False
show_gitlab_edit = False

In template, option value is in theme_{<option>} variables. E.g. to get show_gitlab_edit value, use theme_show_prev_next variable:

{% if theme_motto %}
    <h5>{{ theme_motto }}</h5>
{% endif %}

Advantage of theme options is they are easy customizable in project’s conf.py html_theme_options. For example:

html_theme = 'mytheme'

html_theme_options = {
    'motto': 'A picture is worth a thousand words.'
}

Previous: How to add a sitemap to the Sphinx project? Next: How to modify Sphinx theme?

TechWriter at work blog