a4a2ed7f99
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
79 lines
2.8 KiB
ReStructuredText
79 lines
2.8 KiB
ReStructuredText
========================
|
|
Team and repository tags
|
|
========================
|
|
|
|
.. image:: http://governance.openstack.org/badges/openstackdocstheme.svg
|
|
:target: http://governance.openstack.org/reference/tags/index.html
|
|
|
|
.. Change things from this point on
|
|
|
|
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`_.
|
|
|
|
.. _`projects governed by the Technical Committee`:
|
|
http://governance.openstack.org/reference/projects/index.html
|
|
|
|
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')
|
|
|
|
|
|
* Free software: Apache License, Version 2.0
|
|
* Release notes: http://docs.openstack.org/releasenotes/openstackdocstheme/
|
|
* Source: http://git.openstack.org/cgit/openstack/openstackdocstheme
|
|
* Bugs: http://bugs.launchpad.net/openstack-manuals
|