add config option to point to the cgit browser

Add a configuration option to let projects set the URL to the cgit
browser for their source. Still try to guess at the location based on
our git URL.

Change-Id: I11455f8a137a029c28a864eb555f69f6c282840b

doc/source/conf.py

@@ -26,6 +26,8 @@ extensions = [
     'oslosphinx'
 ]
 
+oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/oslosphinx'
+
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable

doc/source/usage.rst

@@ -13,3 +13,14 @@ If you are an incubating project, set::
   html_theme_options = {'incubating': True}
 
 in your conf.py as well, to enable the Incubation theme.
+
+Linking to a Source Repository
+==============================
+
+``oslosphinx`` defines a configuration option ``oslosphinx_cgit_link``
+which should be the URL to the git repository browser for the project
+being documented. The default is a guess, and will be right for a lot
+of projects, but to ensure that it is correct in all situations it is
+best to set the value in conf.py::
+
+  oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/oslosphinx'

oslosphinx/__init__.py

@@ -18,22 +18,24 @@ import subprocess
 
 
 CGIT_BASE = 'http://git.openstack.org/cgit/'
-_cgit_link = None
+
+
+def _guess_cgit_link():
+    try:
+        git_remote = subprocess.check_output(
+            ['git', 'config', '--local', '--get', 'remote.origin.url']
+        )
+    except subprocess.CalledProcessError:
+        return None
+    else:
+        parsed = parse.urlparse(git_remote)
+        return CGIT_BASE + parsed.path.lstrip('/')
 
 
 def _html_page_context(app, pagename, templatename, context, doctree):
-    global _cgit_link
-    if _cgit_link is None:
-        try:
-            git_remote = subprocess.check_output(
-                ['git', 'config', '--local', '--get', 'remote.origin.url']
-            )
-        except subprocess.CalledProcessError:
-            _cgit_link = 'unknown'
-        else:
-            parsed = parse.urlparse(git_remote)
-            _cgit_link = CGIT_BASE + parsed.path.lstrip('/')
-    context['cgit_link'] = _cgit_link
+    # Insert the cgit link into the template context.
+    context['cgit_link'] = app.config.oslosphinx_cgit_link
+    return context
 
 
 def builder_inited(app):
@@ -60,3 +62,7 @@ def builder_inited(app):
 
 def setup(app):
     app.connect('builder-inited', builder_inited)
+    # Try to guess at the default value for where the cgit repository
+    # is.
+    cgit_link = _guess_cgit_link()
+    app.add_config_value('oslosphinx_cgit_link', cgit_link, 'env')