Sphinx templating

See also

Creating themes

See also

http://sphinx-doc.org/latest/theming.html?highlight=template

As said, themes are either a directory or a zipfile (whose name is the theme name), containing the following:

  • A theme.conf file, see below.

  • HTML templates, if needed.

  • A static/ directory containing any static files that will be copied to the output static directory on build. These can be images, styles, script files.

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 inherit setting gives the name of a “base theme”, or none. The base theme will be used to locate missing templates (most themes will not have to supply most templates if they use basic as the base theme), its options will be inherited, and all of its static files will be used as well.

  • The stylesheet setting gives the name of a CSS file which will be referenced in the HTML header. If you need more than one CSS file, either include one from the other via CSS’ @import, or use a custom HTML template that adds <link rel="stylesheet"> tags as necessary. Setting the html_style config value will override this setting.

  • The pygments_style setting gives the name of a Pygments style to use for highlighting. This can be overridden by the user in the pygments_style config value.

  • The options section contains pairs of variable names and default values. These options can be overridden by the user in html_theme_options and are accessible from all templates as theme_<name>.

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.