OpenStack Sphinx themes¶
openstackdocstheme is a Sphinx documentation extension that includes theme support for Open Infrastructure Foundation projects.
The openstackdocs theme is used for 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.
The starlingxdocs theme is used for documentation that is published to docs.starlingx.io. It is intended for use by StarlingX projects governed by the Technical Steering 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 on
https://opendev.org
and bug tracker.openstackdocs_repo_name
The prefix and repo name. For example,
'openstack/python-glanceclient'
.openstackdocs_use_storyboard
Set to
True
if using StoryBoard.Note
If using StoryBoard, do not set
bug_project
andbug_tag
options.openstackdocs_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. This option can be removed if using StoryBoard.openstackdocs_bug_tag
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 openstackdocs_repo_name = 'openstack/python-glanceclient' openstackdocs_bug_project = 'python-glanceclient' openstackdocs_bug_tag = ''
One example for a project using StoryBoard:
# openstackdocstheme options openstackdocs_repo_name = 'openstack/infra-manual' openstackdocs_use_storyboard = true
Remove the options that will be automatically configured by the theme.
project
html_last_updated_fmt
Configure version-related options.
For everything except documentation in the
api-guide
,api-ref
, andreleasenotes
paths, the theme will automatically set the version of your documentation. This behavior can be manually configured by setting theopenstackdocs_auto_version
option to eitherTrue
orFalse
.If your documentation is auto-versioned, you should remove the options related to versioning as they will be overridden.
version
release
(Optional) Manually configure the project name.
The theme will automatically set the project name used in your documentation. You can disable this behavior by setting the
openstackdocs_auto_name
option tofalse
and configuring theproject
option to the name you wish to use.(Optional) Link to the PDF file.
If you build a PDF file as well, the theme can create a link to it. Set
openstack_pdf_link
toTrue
to generate the link. The file is expected to be nameddoc-<shortname>.pdf
and placed in the top-level directory where<shortname>
is theopenstackdocs_repo_name
. For example with:openstackdocs_repo_name = "openstack/python-glanceclient"
the shortname is
python-glanceclient
and the filename will bedoc-python-glanceclient.pdf
. Use the variableopenstackdocs_pdf_filename
to override the generated file name.
Changed in version 2.2.0: The config options openstack_pdf_link
and
openstackdocs_pdf_filename
were introduced.
Changed in version 2.1.0: The repository_name
, bug_project
, bug_tag
and use_storyboard
config options were renamed to openstackdocs_repo_name
,
openstackdocs_bug_project
, openstackdocs_bug_tag
and
openstackdocs_use_storyboard
, respectively. Aliases are provided but
these will be removed in a future release.
Changed in version 2.1.0: The openstackdocs_auto_version
and openstackdocs_auto_name
config
options were added.
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 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.
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,
# ...
}
The TOC on the left contains a global section (to navigate between pages) and a local section (showing page contents). If the TOC is displayed in the text, you might want to disable the global section of the TOC:
html_theme_options = {
# ...
"display_global_toc_section": False,
# ...
}
If you are using this theme for something other than docs.openstack.org, you can customize the root title (“OpenStack Docs”) that appears in the page title and the left arrow tooltip:
html_theme_options = {
# ...
"root_title": "OpenStack Governance",
# ...
}
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:
openstack_projects = ['horizon']
Then in the documentation source, link to a target using syntax like:
:horizon-doc:`Launching Instances with Horizon <user/launch-instances.html>`
Note
Do not use this feature to reference projects that have a different branching policy, for example, only have a master branch.
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.