Metadata-Version: 2.0
Name: openstackdocstheme
Version: 1.10.0
Summary: OpenStack Docs Theme
Home-page: http://docs.openstack.org/
Author: OpenStack
Author-email: openstack-dev@lists.openstack.org
License: UNKNOWN
Platform: UNKNOWN
Classifier: Environment :: OpenStack
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Documentation
Requires-Dist: pbr (!=2.1.0,>=2.0.0)

========================
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



