automate some of the extension setup

Remove the code that was trying to force openstackdocs to be the
theme. It was using the wrong name anyway, so it didn't work, and we
don't want to use that approach any more.

Add configuration options to make it easier to pass the git repository
and bug tracker information.

Add an event processor to update the html page context for each
page. Include the gitsha by looking at the repository. Include the
giturl by looking at the configuration option for the repo name and
building the URL from it.

Include the bug project and tag values based on the configuration
options.

Update the instructions for enabling the theme to include adding the
module to the list of extensions to turn on all of the above.

Add the openstackdocs theme automatically when the extension is
initialized.

Change-Id: Icf3a40ed104cfd828f532f6f2b112ed02f996ff5
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

README.rst

@@ -39,52 +39,43 @@ 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.
+and to add ``'openstackdocstheme'`` to the list of extensions Sphinx
+needs to initialize::
 
-* ``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.
+   extensions = [
+       # ...
+       'openstackdocstheme',
+       # ...
+   ]
 
-Your ``conf.py`` will be like as follow::
+Set the options to link to the git repository and bug tracker.
+
+``repository_name``
+    The prefix and repo name. For example,
+    ``'openstack/python-glanceclient'``.
+
+``bug_project``
+    The launchpad project name. For example, ``python-glanceclient``.
+
+``bug_tag``
+   Launchpad bug tag. If unspecified, no tag is set.  The default is
+   empty.
+
+For example::
+
+    # openstackdocstheme options
+    repository_name = 'openstack/python-glanceclient'
+    bug_project = 'python-glanceclient'
+    bug_tag = ''
+
+Enable the "last-updated" information by setting the format for the
+timestamp::
 
-   # 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

doc/source/conf.py

@@ -39,6 +39,13 @@ latex_custom_template = r"""
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
+extensions = ['openstackdocstheme']
+
+# openstackdocstheme options
+repository_name = 'openstack/openstackdocstheme'
+bug_project = 'openstack-doc-tools'
+bug_tag = 'openstackdocstheme'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -69,23 +76,6 @@ version = '1.0'
 # The full version, including alpha/beta/rc tags.
 release = '1.0'
 
-# A few variables have to be set for the log-a-bug feature.
-#   giturl: The location of conf.py on Git. Must be set manually.
-#   gitsha: The SHA checksum of the bug description. Automatically extracted from git log.
-#   bug_tag: Tag for categorizing the bug. Must be set manually.
-# These variables are passed to the logabug code via html_context.
-giturl = u'https://git.openstack.org/cgit/openstack/openstackdocstheme/tree/doc/source'
-git_cmd = ["/usr/bin/git", "rev-parse", "HEAD"]
-try:
-    gitsha = subprocess.Popen(
-        git_cmd, stdout=subprocess.PIPE).communicate()[0].decode('utf-8').strip('\n')
-except OSError:
-    warnings.warn('Cannot get gitsha from git repository. Setting to None')
-    gitsha = None
-bug_tag = "doc-builds"
-
-html_context = {"gitsha": gitsha, "bug_tag": bug_tag, "giturl": giturl}
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
@@ -143,7 +133,7 @@ html_theme = 'openstackdocs'
 #html_theme_options = {"sidebar_dropdown": "api_ref"}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [openstackdocstheme.get_html_theme_path()]
+# html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

openstackdocstheme/__init__.py

@@ -13,24 +13,15 @@
 #    under the License.
 
 import os
+import subprocess
+
+_giturl = 'https://git.openstack.org/cgit/{}/tree/doc/source'
+_html_context_data = None
 
 
 def builder_inited(app):
     theme_dir = os.path.join(os.path.dirname(__file__), 'theme')
     app.info('Using openstackdocstheme Sphinx theme from %s' % theme_dir)
-    # Insert our theme directory at the front of the search path and
-    # force the theme setting to use the one in the package. This is
-    # done here, instead of in setup(), because conf.py is read after
-    # setup() runs, so if the conf contains these values the user
-    # values overwrite these. That's not bad for the theme, but it
-    # breaks the search path.
-    app.config.html_theme_path.insert(0, theme_dir)
-    # Set the theme name
-    app.config.html_theme = 'openstackdocstheme'
-    # Re-initialize the builder, if it has the method for setting up
-    # the templates and theme.
-    if hasattr(app.builder, 'init_templates'):
-        app.builder.init_templates()
 
 
 def get_pkg_path():
@@ -54,5 +45,33 @@ def get_openstack_logo_path():
     return os.path.join(get_pkg_path(), *args)
 
 
+def _html_page_context(app, pagename, templatename, context, doctree):
+    global _html_context_data
+    if _html_context_data is None:
+        _html_context_data = {}
+        _html_context_data['gitsha'] = subprocess.check_output(
+            ['git', 'rev-parse', 'HEAD'],
+        ).decode('utf-8').strip()
+        repo_name = app.config.repository_name
+        if repo_name:
+            _html_context_data['giturl'] = _giturl.format(repo_name)
+        bug_project = app.config.bug_project
+        if bug_project:
+            _html_context_data['bug_project'] = bug_project
+        bug_tag = app.config.bug_tag
+        if bug_tag:
+            _html_context_data['bug_tag'] = bug_tag
+    context.update(_html_context_data)
+
+
 def setup(app):
+    app.info('connecting events for openstackdocstheme')
     app.connect('builder-inited', builder_inited)
+    app.connect('html-page-context', _html_page_context)
+    app.add_config_value('repository_name', '', 'env')
+    app.add_config_value('bug_project', '', 'env')
+    app.add_config_value('bug_tag', '', 'env')
+    app.add_html_theme(
+        'openstackdocs',
+        os.path.abspath(os.path.dirname(__file__)) + '/theme/openstackdocs',
+    )