Fix previous releases sidebar feature for ecosystem projects (#267)

Closes #235. As
summarized in
#235 (comment),
we were only handling Terra properly.

I used test driven development to ensure I handled all the edge cases.

## Leverages ecosystem redirects

We are now successfully redirecting ecosystem projects, e.g.
`documentation/experiments/` to `ecosystem/experiments`. That simplifies
the edge cases we need to handle: we only need to handle Terra
(`documentation/`) and Ecosystem (`ecosystem/<project>`).

## Adds `utils.js` file

Having a dedicated JavaScript file for our logic will make it easier to
find all our custom logic. It also allows us to test the contents with
Jest.

__tests__/utils.test.js

@@ -1,5 +1,90 @@
-const { expect, test } = require("@jest/globals");
+const { describe, expect, test } = require("@jest/globals");
+const {
+  determineVersionURL: determineVersionURLPytorch,
+} = require("../qiskit_sphinx_theme/pytorch_base/static/js/utils.js");
+const {
+  determineVersionURL: determineVersionURLFuro,
+} = require("../qiskit_sphinx_theme/furo/base/static/js/utils.js");
 
-test("dummy test to check Jest infrastructure works. Remove after", () => {
-  expect(true).toBe(true);
+const checkVersionURL = (inputURL, version, expected) => {
+  expect(determineVersionURLPytorch(inputURL, version)).toEqual(expected);
+  expect(determineVersionURLFuro(inputURL, version)).toEqual(expected);
+};
+
+describe("determineVersionURL()", () => {
+  test("handles the /ecosystem scheme", () => {
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/nature",
+      "0.4",
+      "/ecosystem/nature/stable/0.4/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/finance",
+      "0.6",
+      "/ecosystem/finance/stable/0.6/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/nature/index.html",
+      "0.4",
+      "/ecosystem/nature/stable/0.4/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/nature/apidocs/index.html",
+      "0.4",
+      "/ecosystem/nature/stable/0.4/index.html"
+    );
+
+    // Already on stable URL:
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/nature/stable/0.6/index.html",
+      "0.4",
+      "/ecosystem/nature/stable/0.4/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/finance/stable/0.7/index.html",
+      "0.6",
+      "/ecosystem/finance/stable/0.6/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/ecosystem/nature/stable/0.6/apidocs/index.html",
+      "0.4",
+      "/ecosystem/nature/stable/0.4/index.html"
+    );
+  });
+
+  test("handles Terra", () => {
+    checkVersionURL(
+      "https://qiskit.org/documentation",
+      "0.4",
+      "/documentation/stable/0.4/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/documentation/index.html",
+      "0.4",
+      "/documentation/stable/0.4/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/documentation/apidocs/index.html",
+      "0.4",
+      "/documentation/stable/0.4/index.html"
+    );
+
+    // Already on stable URL:
+    checkVersionURL(
+      "https://qiskit.org/documentation/stable/0.6/index.html",
+      "0.4",
+      "/documentation/stable/0.4/index.html"
+    );
+    checkVersionURL(
+      "https://qiskit.org/documentation/stable/0.6/apidocs/index.html",
+      "0.4",
+      "/documentation/stable/0.4/index.html"
+    );
+  });
+
+  test("return null if the URL does not match", () => {
+    checkVersionURL("https://qiskit.org", "0.4", null);
+    checkVersionURL("https://qiskit.org/ecosystem", "0.4", null);
+    checkVersionURL("file:///Users/qiskit/index.html", "0.4", null);
+  });
 });

qiskit_sphinx_theme/furo/base/custom_templates/extra_head.html

@@ -2,6 +2,7 @@
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;700&family=IBM+Plex+Sans:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
 <script src="{{ pathto('_static/js/web-components/top-nav-bar.js', 1) }}"></script>
+<script type="text/javascript" src="{{ pathto('_static/js/utils.js', 1) }}"></script>
 
 {%- if analytics_enabled %}
 <script>

qiskit_sphinx_theme/furo/base/custom_templates/sidebar_version_list.html

@@ -2,7 +2,9 @@
     <div class="sidebar-l1-expandable">Previous Releases</div>
     <div class="sidebar-subheadings">
         {% for version in version_list | sort(reverse=True) %}
-            <div class="sidebar-l2"><a href="/documentation/stable/{{ version }}/index.html">{{ version }}</a></div>
+            <div class="sidebar-l2">
+                <a href="#" onclick="redirectToVersion( {{ version }} )" rel="nofollow">{{ version }}</a>
+            </div>
         {% endfor %}
     </div>
 {% endif %}

qiskit_sphinx_theme/furo/base/static/js/utils.js

@@ -0,0 +1,45 @@
+/**
+ * Determine the URL for the version's documentation.
+ *
+ * @param version currentURL: The current browser's URL.
+ * @param version string: The version of the docs, e.g. '0.4'.
+ * @returns string | null
+ */
+const determineVersionURL = (currentURL, version) => {
+  // We expect URls to either be `documentation/` (Terra) or `ecosystem/<project>`.
+  const match = currentURL.match(
+    /(?:.*)(\/ecosystem\/\w+|\/documentation)(?:\/|$)/
+  );
+  if (!match) {
+    return null;
+  }
+  return `${match[1]}/stable/${version}/index.html`;
+};
+
+/**
+ * Change the browser's URL to the version's documentation. Do nothing if the current URL
+ * is unexpected.
+ *
+ * @param version string: The version of the docs, e.g. '0.4'.
+ */
+const redirectToVersion = (version) => {
+  const result = determineVersionURL(window.location.href, version);
+  if (!result) {
+    console.error(
+      `Could not determine the version URL for ${window.location.href} with version ${version}`
+    );
+    return;
+  }
+  window.location.href = result;
+};
+
+if (typeof module === "undefined") {
+  // Export utils for Sphinx usage. Assigning the values to `window` makes
+  // the values available globally.
+  window.redirectToVersion = redirectToVersion;
+} else {
+  // Export utils for Jest testing.
+  module.exports = {
+    determineVersionURL,
+  };
+}

qiskit_sphinx_theme/pytorch_base/layout.html

@@ -165,6 +165,7 @@
     <script type="text/javascript" src="{{ pathto('_static/js/vendor/bootstrap.min.js', 1) }}"></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/list.js/1.5.0/list.min.js"></script>
     <script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script>
+    <script type="text/javascript" src="{{ pathto('_static/js/utils.js', 1) }}"></script>
 
   <script type="text/javascript" src="{{ pathto('_static/js/vendor/anchor.min.js', 1) }}"></script>
 

qiskit_sphinx_theme/pytorch_base/sidebar.html

@@ -18,7 +18,9 @@
             <div class="sidebar-l1-expandable">Previous Releases</div>
             <div class="sidebar-subheadings">
                 {% for version in version_list | sort(reverse=True) %}
-                    <div class="sidebar-l2"><a href="/documentation/stable/{{ version }}/index.html">{{ version }}</a></div>
+                    <div class="sidebar-l2">
+                        <a href="#" onclick="redirectToVersion( {{ version }} )" rel="nofollow">{{ version }}</a>
+                    </div>
                 {% endfor %}
             </div>
         {% endif %}

qiskit_sphinx_theme/pytorch_base/static/js/utils.js

@@ -0,0 +1,45 @@
+/**
+ * Determine the URL for the version's documentation.
+ *
+ * @param version currentURL: The current browser's URL.
+ * @param version string: The version of the docs, e.g. '0.4'.
+ * @returns string | null
+ */
+const determineVersionURL = (currentURL, version) => {
+  // We expect URls to either be `documentation/` (Terra) or `ecosystem/<project>`.
+  const match = currentURL.match(
+    /(?:.*)(\/ecosystem\/\w+|\/documentation)(?:\/|$)/
+  );
+  if (!match) {
+    return null;
+  }
+  return `${match[1]}/stable/${version}/index.html`;
+};
+
+/**
+ * Change the browser's URL to the version's documentation. Do nothing if the current URL
+ * is unexpected.
+ *
+ * @param version string: The version of the docs, e.g. '0.4'.
+ */
+const redirectToVersion = (version) => {
+  const result = determineVersionURL(window.location.href, version);
+  if (!result) {
+    console.error(
+      `Could not determine the version URL for ${window.location.href} with version ${version}`
+    );
+    return;
+  }
+  window.location.href = result;
+};
+
+if (typeof module === "undefined") {
+  // Export utils for Sphinx usage. Assigning the values to `window` makes
+  // the values available globally.
+  window.redirectToVersion = redirectToVersion;
+} else {
+  // Export utils for Jest testing.
+  module.exports = {
+    determineVersionURL,
+  };
+}