From 6a3b2495d337ea8e0225b90b4435511e9aa9266a Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 23 Jul 2024 16:24:18 +0200 Subject: [PATCH] Generate version selector dynamically via JavaScript _Note this is just a proof of concept to start the conversation._ While working on the idea to generate the version/language selectors and combine them with the data fetched from Read the Docs API, I realized that if we are migrating only _one_ version to Read the Docs and using a proxy to serve it at the official `docs.python.org` domain, there is no need to use a different version/language selector at all --since all the URLs will be the same and all the JavaScript logic will be the same. The proxy will do the magic to redirect to Read the Docs _only_ the versions configured in the proxy [^1]. However, since when building on Read the Docs the variables `VERSIONS` and `LANGUAGES` are not passed, we need to populate them dynamically with JavaScript when the page is served. **ToDo**: - Populate `all_languages` in the same way. Do we have a JSON file from where we can populate the `LANGUAGES` variable? - Move this `switchers.js` file to https://github.com/python/cpython/tree/main/Doc/tools/static ---- I'm opening a PR here to show what I'm thinking and discuss if this is the approach we want to follow. BTW, the code is not tested. I just wrote it as an example to show what I'm thinking is the direction. Related: - https://github.com/python/python-docs-theme/pull/193/ - https://github.com/python/docs-community/issues/5 [^1]: Once all the versions/languages are migrated to Read the Docs, we won't require the `release-cycle.json` nor other file to populate the `LANGUAGES` variable because this data will come from Read the Docs Addons API. --- templates/switchers.js | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/templates/switchers.js b/templates/switchers.js index 29204ae..babac8e 100644 --- a/templates/switchers.js +++ b/templates/switchers.js @@ -1,4 +1,4 @@ -(function() { +(async function() { 'use strict'; if (!String.prototype.startsWith) { @@ -18,7 +18,19 @@ '(?:dev)', '(?:release/\\d.\\d[\\x\\d\\.]*)']; - const all_versions = $VERSIONS; + // Fetch all available documentation versions from `release-cycle.json` + const releaseCycleURL = "https://raw.githubusercontent.com/python/devguide/main/include/release-cycle.json"; + const releaseCycleResponse = await fetch(releaseCycleURL, { method: "GET"}); + if (!releaseCycleResponse.ok) { + throw new Error("Error downloading release-cycle.json file."); + } + const releaseCycleData = await releaseCycleResponse.json(); + + const all_versions = new Array(); + for (const version of releaseCycleData ) { + all_versions.push(version); + } + // TODO: fetch available languges from an external JSON file const all_languages = $LANGUAGES; function quote_attr(str) {