New in version 0.6.
Sphinx supports changing the appearance of its HTML output via themes. A theme is a collection of HTML templates, stylesheet(s) and other static files. Additionally, it has a configuration file which specifies from which theme to inherit, which highlighting style to use, and what options exist for customizing the theme’s look and feel.
Themes are meant to be project-unaware, so they can be used for different projects without change.
Using an existing theme is easy. If the theme is builtin to Sphinx, you only need to set the html_theme config value. With the html_theme_options config value you can set theme-specific options that change the look and feel. For example, you could have the following in your conf.py:
html_theme = "default"
html_theme_options = {
"rightsidebar": "true",
"relbarbgcolor": "black"
}
That would give you the default theme, but with a sidebar on the right side and a black background for the relation bar (the bar with the navigation links at the page’s top and bottom).
If the theme does not come with Sphinx, it can be in two static forms: either a directory (containing theme.conf and other needed files), or a zip file with the same contents. Either of them must be put where Sphinx can find it; for this there is the config value html_theme_path. It gives a list of directories, relative to the directory containing conf.py, that can contain theme directories or zip files. For example, if you have a theme in the file blue.zip, you can put it right in the directory containing conf.py and use this configuration:
html_theme = "blue"
html_theme_path = ["."]
The third form provides your theme path dynamically to Sphinx if the setuptools package is installed. You can provide an entry point section called sphinx_themes in your setup.py file and write a get_path function that has to return the directory with themes in it:
// in your 'setup.py'
setup(
...
entry_points = {
'sphinx_themes': [
'path = your_package:get_path',
]
},
...
)
// in 'your_package.py'
from os import path
package_dir = path.abspath(path.dirname(__file__))
template_path = path.join(package_dir, 'themes')
def get_path():
return template_path
New in version 1.2: ‘sphinx_themes’ entry_points feature.
| Theme overview | |
default |
sphinxdoc |
scrolls |
agogo |
traditional |
nature |
haiku |
pyramid |
Sphinx comes with a selection of themes to choose from.
These themes are:
basic – This is a basically unstyled layout used as the base for the other themes, and usable as the base for custom themes as well. The HTML contains all important elements like sidebar and relation bar. There are these options (which are inherited by the other themes):
default – This is the default theme, which looks like the Python documentation. It can be customized via these options:
There are also various color and font options that can change the color scheme without having to write a custom stylesheet:
sphinxdoc – The theme used for this documentation. It features a sidebar on the right side. There are currently no options beyond nosidebar and sidebarwidth.
scrolls – A more lightweight theme, based on the Jinja documentation. The following color options are available:
agogo – A theme created by Andi Albrecht. The following options are supported:
nature – A greenish theme. There are currently no options beyond nosidebar and sidebarwidth.
pyramid – A theme from the Pyramid web framework project, designed by Blaise Laflamme. There are currently no options beyond nosidebar and sidebarwidth.
haiku – A theme without sidebar inspired by the Haiku OS user guide. The following options are supported:
traditional – A theme resembling the old Python documentation. There are currently no options beyond nosidebar and sidebarwidth.
epub – A theme for the epub builder. This theme tries to save visual space which is a sparse resource on ebook readers. The following options are supported:
As said, themes are either a directory or a zipfile (whose name is the theme name), containing the following:
The theme.conf file is in INI format [1] (readable by the standard Python ConfigParser module) and has the following structure:
[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
[options]
variable = default value
The guide to templating is helpful if you want to write your own templates. What is important to keep in mind is the order in which Sphinx searches for templates:
When extending a template in the base theme with the same name, use the theme name as an explicit directory: {% extends "basic/layout.html" %}. From a user templates_path template, you can still use the “exclamation mark” syntax as described in the templating document.
Since theme options are meant for the user to configure a theme more easily, without having to write a custom stylesheet, it is necessary to be able to template static files as well as HTML files. Therefore, Sphinx supports so-called “static templates”, like this:
If the name of a file in the static/ directory of a theme (or in the user’s static path, for that matter) ends with _t, it will be processed by the template engine. The _t will be left from the final file name. For example, the default theme has a file static/default.css_t which uses templating to put the color options into the stylesheet. When a documentation is built with the default theme, the output directory will contain a _static/default.css file where all template tags have been processed.
| [1] | It is not an executable Python file, as opposed to conf.py, because that would pose an unnecessary security risk if themes are shared. |