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.

Update the requirements list for your project to include openstackdocstheme (usually in test-requirements.txt).
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.
Then modify your Sphinx settings in conf.py to include:
```
html_theme = 'openstackdocs'
```
and to add 'openstackdocstheme' to the list of extensions Sphinx needs to initialize:
```
extensions = [
    # ...
    'openstackdocstheme',
    # ...
]
```
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 = ''
```

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'

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"}

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"}
```

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.

demo/index

3.7 KiB Raw Blame History

OpenStack docs.openstack.org Sphinx theme

Using the theme

Demonstration example

3.7 KiB

Raw Blame History