89b0475539
Some OpenStack contributors have expressed concern about having Google Analytics tracking codes embedded in all of the HTML documentation generated by the use of this theme. In addition to these concerns, which mostly focus on privacy, having the Google Analytics tracking code used widely runs the risk of creating misleading analytics data. This change adopts an approach used by the Alabaster theme, which enables Google Analytics tracking to be optional. Tracking is now controlled by the theme settings in conf.py using a new theme option, 'analytics_tracking_code'. If present, this causes the HTML to include the analytics tracking, with the provided code being used. If not present, the Google Analytics snippet is excluded from the documentation. To avoid breakage, this commit uses the current hard-coded Google Analytics tracking code as the default value of the option, which means that most users will not notice any change and may continue to be accidentally opted in to Google Analytics tracking. Change-Id: I156151c3f458931f13716b4a32087afe57483794
OpenStack docs.openstack.org Sphinx Theme
Theme and extension support for Sphinx documentation that is published to docs.openstack.org. Intended for use by OpenStack projects.
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:
# We ask git for the SHA checksum
# The git SHA checksum is used by "log-a-bug"
git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
gitsha = os.popen(git_cmd).read().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'- Free software: Apache License, Version 2.0
- Documentation: http://docs.openstack.org/developer/openstackdocstheme
- Source: http://git.openstack.org/cgit/openstack/openstackdocstheme
- Bugs: http://bugs.launchpad.net/openstack-manuals