OpenStack Sphinx theme

OpenStack Sphinx theme

openstackdocstheme is a theme and extension support for Sphinx documentation that is published to and

It is intended for use by OpenStack projects governed by the Technical Committee.

Using the theme


Prior to using this theme, ensure your project can use the OpenStack brand by referring to the brand guidelines at


Some of the settings below are included in the file generated by Sphinx when you initialize a project, so they may already have values that need to be changed.

  1. Update the requirements list for your project to include openstackdocstheme (usually in test-requirements.txt).

  2. If your project previously used the oslosphinx theme (without modifying the header navigation), remove oslosphinx from your requirements list, and then in your you can remove the import statement and extension listing for oslosphinx.

  3. Once done, you should add 'openstackdocstheme' to the list of extensions Sphinx needs to initialize and configure the theme:

    extensions = [
        # ...
        # ...
    html_theme = 'openstackdocs'
  4. Set the options to link to the git repository and bug tracker.


    The prefix and repo name. For example, 'openstack/python-glanceclient'.


    Set to True if using StoryBoard.


    If using StoryBoard, do not set bug_project and bug_tag options.


    The project name or ID. For launchpad, it’s a string like python-glanceclient. If unspecified, the “Report a bug” links are not shown. This option can be removed if using StoryBoard.


    Launchpad bug tag. If unspecified, no tag is set. The default is empty. This option can be removed if using StoryBoard.

    One example for a project using launchpad:

    # openstackdocstheme options
    repository_name = 'openstack/python-glanceclient'
    bug_project = 'python-glanceclient'
    bug_tag = ''

    One example for a project using StoryBoard:

    # openstackdocstheme options
    repository_name = 'openstack-infra/infra-manual'
    use_storyboard = True
  5. Remove the options that will be automatically configured by the theme.

    • project
    • html_last_updated_fmt
    • latex_engine
    • latex_elements

    In addition, if your documentation is versioned, you should remove the options related to versioning.

    • version
    • release

Changed in version 1.20: In older versions of openstackdocstheme, it was necessary to manually configure the html_last_updated_fmt option for HTML output and the latex_engine and latex_elements options if you required PDF output. This is no longer the case as these attributes are now configured automatically.

Additional Configuration

If you are using this theme for API reference documentation, set the sidebar navigation in the html_theme_options in the file:

# To use the API Reference sidebar dropdown menu,
# uncomment the html_theme_options parameter.  The theme
# variable, sidebar_dropdown, should be set to `api_ref`.
# Otherwise, the list of links for the User and Ops docs
# appear in the sidebar dropdown menu.
html_theme_options = {
    # ...
    "sidebar_dropdown": "api_ref",
    "sidebar_mode": "toc",
    # ...

If you are using this theme for documentation you want to release based on git tags on your repository, set the release dropdown menu option in the html_theme_options in the file. By default it is set to False:

html_theme_options = {
    # ...
    "show_other_versions": "True",
    # ...

If you are using this theme for a project with published documentation that predates the Mitaka release cycle, set the earliest published version in the html_theme_options in the file to the name of the first series with documentation available. By default it is set to None:

html_theme_options = {
    # ...
    "earliest_published_series": "grizzly",
    # ...


Do not use this for release-notes as they are always published as one document with internal versioning.

A badge pointing out the support status of a document is shown now for repositories that have stable/ branches. The badge is not displayed for api-ref, api-guide and releasenotes documents. It can be disabled with the display_badge html theme option:

    html_theme_options = {
    # ...
    "display_badge": False,
    # ...

Demonstration example

The demo documentation provides example output to ensure it matches what’s expected. The link below points to the example output when using the theme for all documentation that is not API reference.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.