Skip to content

Commit

Permalink
Generate version selector dynamically via JavaScript
Browse files Browse the repository at this point in the history
_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.

- 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:
- python/python-docs-theme#193
- python/docs-community#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.
  • Loading branch information
humitos committed Jul 23, 2024
1 parent 2135304 commit 0a2e3a8
Showing 1 changed file with 14 additions and 2 deletions.
16 changes: 14 additions & 2 deletions templates/switchers.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(function() {
(async function() {
'use strict';

if (!String.prototype.startsWith) {
Expand All @@ -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) {
Expand Down

0 comments on commit 0a2e3a8

Please sign in to comment.