Add support for mult-version links in side-bar.

Author: Diptorup Deb

docs/CMakeLists.txt

@@ -7,6 +7,13 @@ option(DPCTL_ENABLE_DOXYREST
     OFF
 )
 
+# Option to add verion links to the side bar. This option is primarily
+# intended to generate dpctl's docs for our github.io page.
+option(DPCTL_USE_MULTIVERSION_TEMPLATE
+    "Enable adding verion links to side bar"
+    OFF
+)
+
 # This function defines everything needed to generate Doxygen docs
 function(_setup_doxygen)
     # We generate doxygen only for the public headers to keep the Doxyrest

docs/_templates/versions.html

@@ -0,0 +1,22 @@
+{% if READTHEDOCS or display_lower_left %}
+{# Add rst-badge after rst-versions for small badge style. #}
+  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version" data-toggle="rst-current-version">
+      <span class="fa fa-book"> Other versions</span>
+      v: {{ current_version }}
+      <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+      {% if versions|length >= 1 %}
+      <dl>
+        <dt>{{ _('Versions') }}</dt>
+        {% for slug, url in versions %}
+          {% if slug == current_version %} <strong> {% endif %}
+          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+          {% if slug == current_version %} </strong> {% endif %}
+        {% endfor %}
+      </dl>
+      {% endif %}
+    </div>
+  </div>
+{% endif %}

docs/conf.in

@@ -98,3 +98,44 @@ html_theme_options = {
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
+
+# When the cmake DPCTL_USE_MULTIVERSION_TEMPLATE flag is set we generate
+# links in the sidebar to the documentation for older versions of dpctl.
+# Note that ths option does not actually generate the documentation for
+# older versions, it only adds links in the sidebar to earlier versions of
+# the documentation. All earlier versions of the documentation should be
+# generated and pushed to the gh-pages branch manually, after which the
+# doc_versions.txt should be updated.
+
+generate_multiversion = "@DPCTL_USE_MULTIVERSION_TEMPLATE@"
+
+if generate_multiversion == "ON":
+    try:
+        html_context
+    except NameError:
+        html_context = dict()
+    html_context["display_lower_left"] = True
+    templates_path = ["_templates"]
+    html_context["current_version"] = version
+    html_context["version"] = version
+
+    # POPULATE LINKS TO OTHER VERSIONS
+    html_context["versions"] = list()
+
+    # Populate the list of documented versions from the doc_versions.tx
+    versions = []
+    with open("doc_versions.txt", "r") as doc_versions:
+        while True:
+            version = doc_versions.readline().strip()
+            if not version:
+                break
+            elif len(version):
+                versions.append(version)
+
+    # FIXME: Remove this hard coding
+    DOC_SITE_NAME = "https://intelpython.github.io/dpctl/"
+
+    for version in versions:
+        html_context["versions"].append(
+            (version, DOC_SITE_NAME + version + "/index.html")
+        )

docs/doc_versions.txt

@@ -0,0 +1,2 @@
+0.6.1
+latest