OpenStack docs.openstack.org Sphinx theme¶

Using the theme¶

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 conf.py you can remove the import statement and extension listing for oslosphinx.

3. Then modify your Sphinx settings in conf.py to include:

   html_theme = 'openstackdocs'
   

4. and to add 'openstackdocstheme' to the list of extensions Sphinx needs to initialize:

   extensions = [
       # ...
       'openstackdocstheme',
       # ...
   ]
   

5. Set the options to link to the git repository and bug tracker.

   repository_name

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

   bug_project

   The project name or ID. For launchpad, it’s a string like python-glanceclient. If your project uses storyboard.openstack.org, use the project number instead like 901. If unspecified, the “Report a bug” links are not shown.

   bug_tag

   Launchpad bug tag. If unspecified, no tag is set. The default is empty.

   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'
   bug_project = '721'
   bug_tag = ''
   

6. Enable the “last-updated” information by setting the format for the timestamp:

   # Must set this variable to include year, month, day, hours, and minutes.
   html_last_updated_fmt = '%Y-%m-%d %H:%M'
   

7. If you are using this theme for API reference documentation, set the sidebar navigation in the html_theme_options in the conf.py 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"}
   

8. 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 conf.py file. By default it is set to False.:

   html_theme_options = {"show_other_versions": "True"}
   
   .. warning::
   
      Use this only if the last *5* tagged versions are accessible
      from the html path where the documents are currently published.
      Remember that the OpenStack infra scripts publish now to
      ``docs.openstack.org/REPO/latest`` and
      ``docs.openstack.org/REPO/TAG``. Thus, check first that the
      URLs are correct for your repository before using this option.
   
      Do not use this for release-notes as they are always published
      as one document with internal versioning.
   

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.