6d816a90e3
Some of the available checks are disabled by default, like: [H106] Don’t put vim configuration in source files [H203] Use assertIs(Not)None to check for None Change-Id: Icb3a3828dff23f3aafe9332c352b38ffbcf17a24
Team and repository tags
OpenStack docs.openstack.org Sphinx Theme
Theme and extension support for Sphinx documentation that is published to docs.openstack.org and developer.openstack.org.
Intended for use by OpenStack projects governed by the Technical Committee.
Using the Theme
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.
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.
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.
Then modify your Sphinx settings in conf.py to
include:
import openstackdocstheme
html_theme = 'openstackdocs'
html_theme_path = [openstackdocstheme.get_html_theme_path()]Also, you must pass the following variables as
html_context so that the "Log a bug" link sends metadata
for the project where the docs reside.
gitsha: (required) git commit hash from which the document is generated.giturl: (required) The location of the document.bug_project: (optional) Launchpad project which a bug is filed to.-
The default value is
openstack-manuals.
bug_tag: (optional) Launchpad bug tag. If unspecified, no tag is set.-
The default is empty.
Your conf.py will be like as follow:
# We ask git for the SHA checksum
# The git SHA checksum is used by "log-a-bug"
git_cmd = ["/usr/bin/git", "rev-parse", "HEAD"]
gitsha = subprocess.Popen(
git_cmd, stdout=subprocess.PIPE).communicate()[0].strip('\n')
giturl = u'https://git.openstack.org/cgit/openstack/<your-project>/tree/doc/source'
# html_context allows us to pass arbitrary values into the html template
html_context = {
"gitsha": gitsha,
"giturl": giturl,
"bug_project": "your-launchpad-project",
# tag that reported bugs will be tagged with
"bug_tag": "your-chosen-tag",
}
# Must set this variable to include year, month, day, hours, and minutes.
html_last_updated_fmt = '%Y-%m-%d %H:%M'You'll also need to add import subprocess to the top of
your conf.py file.
Note
If you're using Python 3 to build, you'll need to adjust the
gitsha command to add a .decode('utf-8')
option.
gitsha = subprocess.Popen(
git_cmd, stdout=subprocess.PIPE).communicate()[0].decode('utf-8').strip('\n')- Free software: Apache License, Version 2.0
- Release notes: https://docs.openstack.org/releasenotes/openstackdocstheme/
- Source: https://git.openstack.org/cgit/openstack/openstackdocstheme
- Bugs: https://launchpad.net/openstack-doc-tools