show release series names not version tags

Rather than linking to recent releases by version, link to the series
docs by name. This allows us to link to a more limited number of
"versions" but maintain those links indefinitely now that we are
planning to retain our documentation online for a more extended period
of time.

The implementation uses dulwich to identify the tags and branches
rather than using git via subprocess.

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

doc/source/index.rst

@@ -101,17 +101,21 @@ Using the theme
 
     html_theme_options = {"show_other_versions": "True"}
 
-    .. warning::
+#. If you are using this theme for a project with published
+   documentation that predates the mitaka release cycle, set the
+   ``earliest_published_series`` theme option to the name of the first
+   series with documentation available.::
 
-       Use this only if the last *5* tagged versions are accessible
+     html_theme_options = {
-       from the html path where the documents are currently published.
+         # ...
-       Remember that the OpenStack infra scripts publish now to
+         "earliest_published_series": "grizzly",
-       ``docs.openstack.org/REPO/latest`` and
+         # ...
-       ``docs.openstack.org/REPO/TAG``. Thus, check first that the
+     }
-       URLs are correct for your repository before using this option.
 
-       Do not use this for release-notes as they are always published
+   .. warning::
-       as one document with internal versioning.
+
+      Do not use this for release-notes as they are always published
+      as one document with internal versioning.
 
 Demonstration example
 =====================

openstackdocstheme/__init__.py

@@ -13,9 +13,10 @@
 #    under the License.
 
 import os
-import string
 import subprocess
 
+import dulwich.repo
+
 _giturl = 'https://git.openstack.org/cgit/{}/tree/doc/source'
 _html_context_data = None
 
@@ -24,28 +25,42 @@ def _get_other_versions(app):
     if not app.config.html_theme_options.get('show_other_versions', False):
         return []
 
-    git_cmd = ["git", "tag", "--sort=v:refname", "--merged"]
+    all_series = []
     try:
-        raw_version_list = subprocess.Popen(
+        repo = dulwich.repo.Repo.discover()
-            git_cmd, stdout=subprocess.PIPE).communicate()[0]
+    except dulwich.repo.NotGitRepository:
-        raw_version_list = raw_version_list.decode("utf-8")
+        return []
-    except UnicodeDecodeError:
-        app.warn('Cannot decode the list based on utf-8 encoding. '
-                 'Not setting "other_versions".')
-        raw_version_list = u''
-    except OSError:
-        app.warn('Cannot get tags from git repository, or no merged tags. '
-                 'Not setting "other_versions".')
-        raw_version_list = u''
 
-    # grab last five that start with a number and reverse the order
+    refs = repo.get_refs()
-    _tags = [t.strip("'") for t in raw_version_list.split('\n')]
+    for ref in refs.keys():
-    other_versions = [
+        ref = ref.decode('utf-8')
-        t for t in _tags if t and t[0] in string.digits
+        if ref.startswith('refs/remotes/origin/stable'):
-        # Don't show alpha, beta or release candidate tags
+            series = ref.rpartition('/')[-1]
-        and 'rc' not in t and 'a' not in t and 'b' not in t
+            all_series.append(series)
-    ][:-5:-1]
+        elif ref.startswith('refs/tags/') and ref.endswith('-eol'):
-    return other_versions
+            series = ref.rpartition('/')[-1][:-4]
+            all_series.append(series)
+    all_series.sort()
+
+    # NOTE(dhellmann): Given when this feature was implemented, we
+    # assume that the earliest version we can link to is for
+    # mitaka. Projects that have older docs online can set the option
+    # to indicate another start point. Projects that come later should
+    # automatically include everything they actually have available
+    # because the start point is not present in the list.
+    earliest_desired = app.config.html_theme_options.get(
+        'earliest_published_series', 'mitaka')
+    if earliest_desired and earliest_desired in all_series:
+        interesting_series = all_series[all_series.index(earliest_desired):]
+    else:
+        interesting_series = all_series
+
+    # Reverse the list because we want the most recent to appear at
+    # the top of the dropdown. The "latest" release is added to the
+    # front of the list by the theme so we do not need to add it
+    # here.
+    interesting_series.reverse()
+    return interesting_series
 
 
 def builder_inited(app):

openstackdocstheme/theme/openstackdocs/theme.conf

@@ -9,3 +9,4 @@ sidebar_mode = toctree
 display_toc = True
 sidebar_dropdown = os_docs
 show_other_versions = False
+earliest_published_series = mitaka

requirements.txt

@@ -3,3 +3,4 @@
 # process, which may cause wedges in the gate later.
 
 pbr!=2.1.0,>=2.0.0 # Apache-2.0
+dulwich>=0.15.0  # Apache-2.0