obda.net

Custom CSS and JS for Sphinx-Generated Documentation

Add a comment

When generating HTML documentation with Sphinx, it is possible to adjust a couple of theme-related settings by defining html_theme_options in your conf.py, e.g.:

html_theme_options = {
    'rightsidebar': True,
    'textcolor': '#333',
}

However, the available options that can be customized are (a) rather restricted, and (b) specific to each theme. The [options] section of a theme’s theme.conf sheds light on what can be done (and what not).

On a global basis, though, you can define html_context to add some custom CSS and JavaScript files:

html_context = {
    'css_files': ['_static/custom.css'],
    'script_files': ['_static/custom.js'],
}

The files listed there will be included last in the generated HTML files’ sources, so it is easy to directly tweak the generated documentation’s final appearance (and, if needed, behavior).

For reference, have a look at Sphinx’s builders.html.StandaloneHTMLBuilder.prepare_writing() and see how self.globalcontext gets populated there.