Project-specific Sphinx Themes

As explained in our Sphinx Themes: Introduction, the theme is basically a folder with theme.toml, some Jinja HTML templates and static files.

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

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.

Example local Sphinx theme

Filesystem hiearchy:

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

And affected conf.py settings:

html_theme = "mytheme"
html_theme_path = ["_themes"]

Comments

comments powered by Disqus