5.8 KiB
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 intest-requirements.txt
).If your project previously used the oslosphinx theme (without modifying the header navigation), remove
oslosphinx
from your requirements list, and then in yourconf.py
you can remove the import statement and extension listing for oslosphinx.Once done, you should add
'openstackdocstheme'
to the list of extensions Sphinx needs to initialize and configure the theme:extensions = [ # ... 'openstackdocstheme', # ... ] html_theme = 'openstackdocs'
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 unspecified, the "Report a bug" links are not shown.If your project uses
storyboard.openstack.org
, it's a string likeopenstack-ci
for the project group...note:: Previously StoryBoard showed numbers, and thus you set this to a project number instead like
901
. Set this to a string instead and also use theuse_storyboard
variable. bug_tag
-
Launchpad bug tag. If unspecified, no tag is set. The default is empty.
use_storyboard
-
Set to
True
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' bug_project = 'openstack-ci' bug_tag = ''
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
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
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",
# ...
}
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
conf.py
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",
# ...
}
Warning
Do not use this for release-notes as they are always published as one document with internal versioning.
By default, a badge is displayed showing which the latest OpenStack release is. You can disable the badge with:
html_theme_options = {
# ...
"display_badge": False,
# ...
}
External Link Helper
The configuration option openstack_projects
can be used
to define custom roles that build links that update automatically when
branches are created for each release series. Builds on the master
branch link to the latest
documentation.
In the conf.py
for the source documentation, add:
= ['horizon'] openstack_projects
Then in the documentation source, link to a target using syntax like:
:horizon-doc:`Launching Instances with Horizon <user/launch-instances.html>`
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