SKA Sphinx Theme

This project provides a Sphinx theme for the SKA documentation hosted on Read the Docs.

It is based on the Read the Docs Sphinx theme, but with:

  • the SKA stylesheet applied;

  • the SKA logo and favicon pre-set as defaults;

  • The standard footer added.

Usage

To apply this theme,

  1. install ska-ser-sphinx-theme into the documentation build environment; that is, add it to your documentation dependencies.

  2. In your conf.py, set the html_theme property:

    html_theme = "ska_ser_sphinx_theme"

    Note that the package is named ska-ser-sphinx-theme (with hyphens), but the theme is named ska_ser_sphinx_theme (with underscores).

Upgrading

If your project previously used sphinx_rtd_theme and directly customised it to apply the SKA style, logos, etc., the you have some cleaning up to do:

  • Your conf.py contains some code to register a stylesheet. It will look something like:

    def setup(app):
    app.add_css_file("css/custom.css")

    or possibly just

    html_style = "css/custom.css"

    That can now be deleted, as can the file that it points to.

  • Your conf.py specifies the logo, maybe through the html_logo or html_logo_url variable, or maybe through an entry in html_context. This specification can now be deleted, as can the logo file that its points to.

  • Your conf.py specifies your favicon in the same way. Delete it, and the favicon file that it points to.

  • You may have a _templates folder containing template files such as layout.html or footer.html. Delete them.