From 78303c65d472267ab11c2958be6b08ce4b20b5d7 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Thu, 4 May 2023 03:07:23 -0600 Subject: [PATCH] Fix previous releases sidebar feature for ecosystem projects (#267) Closes https://github.com/Qiskit/qiskit_sphinx_theme/issues/235. As summarized in https://github.com/Qiskit/qiskit_sphinx_theme/issues/235#issuecomment-1505495938, 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/`). ## 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 | 91 ++++++++++++++++++- .../base/custom_templates/extra_head.html | 1 + .../sidebar_version_list.html | 4 +- .../furo/base/static/js/utils.js | 45 +++++++++ qiskit_sphinx_theme/pytorch_base/layout.html | 1 + qiskit_sphinx_theme/pytorch_base/sidebar.html | 4 +- .../pytorch_base/static/js/utils.js | 45 +++++++++ 7 files changed, 186 insertions(+), 5 deletions(-) create mode 100644 qiskit_sphinx_theme/furo/base/static/js/utils.js create mode 100644 qiskit_sphinx_theme/pytorch_base/static/js/utils.js diff --git a/__tests__/utils.test.js b/__tests__/utils.test.js index 83cc2eb7..18719b10 100644 --- a/__tests__/utils.test.js +++ b/__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); + }); }); diff --git a/qiskit_sphinx_theme/furo/base/custom_templates/extra_head.html b/qiskit_sphinx_theme/furo/base/custom_templates/extra_head.html index 40526af7..5478f427 100644 --- a/qiskit_sphinx_theme/furo/base/custom_templates/extra_head.html +++ b/qiskit_sphinx_theme/furo/base/custom_templates/extra_head.html @@ -2,6 +2,7 @@ + {%- if analytics_enabled %} + diff --git a/qiskit_sphinx_theme/pytorch_base/sidebar.html b/qiskit_sphinx_theme/pytorch_base/sidebar.html index a0cbd6b8..8bb774dd 100644 --- a/qiskit_sphinx_theme/pytorch_base/sidebar.html +++ b/qiskit_sphinx_theme/pytorch_base/sidebar.html @@ -18,7 +18,9 @@
Previous Releases
{% for version in version_list | sort(reverse=True) %} -
{{ version }}
+
+ {{ version }} +
{% endfor %}
{% endif %} diff --git a/qiskit_sphinx_theme/pytorch_base/static/js/utils.js b/qiskit_sphinx_theme/pytorch_base/static/js/utils.js new file mode 100644 index 00000000..095b90c0 --- /dev/null +++ b/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/`. + 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, + }; +}