OpenStack Docs Theme
Project description
========================
Team and repository tags
========================
.. image:: https://governance.openstack.org/badges/openstackdocstheme.svg
:target: https://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`:
https://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
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
Team and repository tags
========================
.. image:: https://governance.openstack.org/badges/openstackdocstheme.svg
:target: https://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`:
https://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
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for openstackdocstheme-1.10.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d72c51365f2076803d22c226171dcf7c9ea725ea489a3e30ae0b01f1e2365f6b |
|
MD5 | 6f1400d1121b0d5eeb601f4d47b95f72 |
|
BLAKE2b-256 | 91a796d0e5134b69e829ccc9c6d57ccda9ef822f24ecf5e4a8f25fd024e9dd65 |
Close
Hashes for openstackdocstheme-1.10.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 36e89ed5651ab308f18c5dbd94c7a841f97c8a8a9a80bef6ebf77c9d605160e3 |
|
MD5 | 95d5cac729e8f050e3a94ed9fcc1c44a |
|
BLAKE2b-256 | de234a0ae5af21bc3f79697f2aa915317e2807fa942f8524300ab9199d353780 |