Allow "Other Versions" section to be configurable

Adds a new option that allows the "Other Versions" section to be removed
if a project isn't interested in showing links to older versions. The
default value is False which means that it will be hidden.

Even though the setting is not backward compatible there are enough
broken documentation links in the OpenStack projects that this should be
opt-in behavior.

Change-Id: Ic4b47b19aa9db38557c37aed7722174b7dbdf4a1
Closes-Bug: #1599260

doc/source/usage.rst

@@ -24,3 +24,14 @@ 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'
+
+Showing Older Versions of Documentation
+=======================================
+
+``oslosphinx`` can automatically add links for previous versions of your
+project's documentation to the sidebar. If this feature is enabled links
+will be generated for each git tag. To enable this behavior, set::
+
+  html_theme_options = {'show_other_versions': True}
+
+in your conf.py.

oslosphinx/__init__.py

@@ -43,6 +43,13 @@ def _guess_cgit_link():
 def _html_page_context(app, pagename, templatename, context, doctree):
     # Insert the cgit link into the template context.
     context['cgit_link'] = app.config.oslosphinx_cgit_link
+    context['other_versions'] = _get_other_versions(app)
+    return None
+
+
+def _get_other_versions(app):
+    if not app.config.html_theme_options.get('show_other_versions', False):
+        return []
 
     git_cmd = ["git", "tag"]
     try:
@@ -62,8 +69,7 @@ def _html_page_context(app, pagename, templatename, context, doctree):
         # Don't show alpha, beta or release candidate tags
         and 'rc' not in t and 'a' not in t and 'b' not in t
     ][:-5:-1]
-    context['other_versions'] = other_versions
-    return None
+    return other_versions
 
 
 def builder_inited(app):

oslosphinx/theme/openstack/theme.conf

@@ -5,3 +5,4 @@ pygments_style = tango
 
 [options]
 incubating = false
+show_other_versions = false