OpenStack docs.openstack.org Sphinx theme

OpenStack docs.openstack.org Sphinx theme

openstackdocstheme is a theme and extension support for Sphinx documentation that is published to docs.openstack.org and developer.openstack.org.

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

Using the theme

Note

Prior to using this theme, ensure your project can use the OpenStack brand by referring to the brand guidelines at https://www.openstack.org/brand.

Note

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 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.

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.