openstack/openstackdocstheme
Code Issues Proposed changes
a4a2ed7f99
openstackdocstheme/README.rst
Leif Madsen a4a2ed7f99 Add note in README about Python 3 changes 
Add a node that explains that for Python 3 you'll need to add a
.decode() function in the gitsha command. Also, note that you
need to import subprocess in the conf.py file.

Change-Id: I1eb42738be74de96fae0940f3e97283351602e95
2017-01-31 15:33:42 +00:00

2.8 KiB
Raw Blame History

Team and repository tags

image

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 http://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 include these variables so that the "Log a bug" link sends metadata for the project where the docs reside. You'll also need to add import subprocess to the top of your conf.py file:

# 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')
# tag that reported bugs will be tagged with
bug_tag = "your-chosen-tag"
# source tree
pwd = os.getcwd()
# html_context allows us to pass arbitrary values into the html template
html_context = {"pwd": pwd, "gitsha": gitsha}
# Must set this variable to include year, month, day, hours, and minutes.
html_last_updated_fmt = '%Y-%m-%d %H:%M'

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')