From fc66a2280c9589c6adbd1daf09f727c2c35800cd Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 18 Mar 2024 16:20:25 +0100 Subject: [PATCH 1/5] Doc: render version/language selector on Read the Docs Integrate the new Read the Docs Addons JavaScript into the Python Docs Sphinx theme to render versions and languages selector nicely. References: * Discord thread: https://discord.com/channels/935215565872693329/1159601953265942589 * Implementation of Addons JavaScript `CustomEvent`: https://github.com/readthedocs/addons/pull/64 * Conversation about using Read the Docs: https://github.com/python/docs-community/issues/5 --- Doc/tools/templates/layout.html | 55 +++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html index 9498b2ccc5af92..e9b45dbb9392ab 100644 --- a/Doc/tools/templates/layout.html +++ b/Doc/tools/templates/layout.html @@ -41,4 +41,59 @@ {{ "}" }} {{ super() }} + + + {% endblock %} From 6fda95c735bcb621c77b69d07416192fc373fe23 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 9 Apr 2024 16:17:34 +0200 Subject: [PATCH 2/5] Doc: adapt code to use API data v1 Follow the changes done in https://github.com/readthedocs/readthedocs.org/pull/11205 --- Doc/tools/templates/layout.html | 79 ++++++++++++++++----------------- 1 file changed, 39 insertions(+), 40 deletions(-) diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html index e9b45dbb9392ab..8e7bb97571c4ec 100644 --- a/Doc/tools/templates/layout.html +++ b/Doc/tools/templates/layout.html @@ -42,7 +42,7 @@ {{ super() }} - + {% endblock %} From 893054939e98a62b4c96eb32a396778809587e7d Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 9 Apr 2024 17:01:16 +0200 Subject: [PATCH 3/5] Doc: add version/language selectors in all the placeholders --- Doc/tools/templates/layout.html | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html index 8e7bb97571c4ec..e896b1ed164476 100644 --- a/Doc/tools/templates/layout.html +++ b/Doc/tools/templates/layout.html @@ -85,13 +85,20 @@ `; - const selectVersionElement = document.querySelector("li.switchers div.version_switcher_placeholder"); - selectVersionElement.innerHTML = versionSelect; - document.querySelector("li.switchers div.version_switcher_placeholder").addEventListener("change", onSwitch); + // Query all the placeholders because there are different ones for Desktop/Mobile + let placeholders = document.querySelectorAll(".version_switcher_placeholder"); + for (placeholder of placeholders) { + placeholder.innerHTML = versionSelect; + let selectElement = placeholder.querySelector("select"); + selectElement.addEventListener("change", onSwitch); + } - const selectLanguageElement = document.querySelector("li.switchers div.language_switcher_placeholder"); - selectLanguageElement.innerHTML = languageSelect; - document.querySelector("li.switchers div.language_switcher_placeholder select").addEventListener("change", onSwitch); + placeholders = document.querySelectorAll(".language_switcher_placeholder"); + for (placeholder of placeholders) { + placeholder.innerHTML = languageSelect; + let selectElement = placeholder.querySelector("select"); + selectElement.addEventListener("change", onSwitch); + } }); }); From 7c27128c15289261c530d457eb580bde1f7405f9 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 9 Apr 2024 17:14:56 +0200 Subject: [PATCH 4/5] Doc: add hardcoded links to the official docs --- Doc/tools/templates/layout.html | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html index e896b1ed164476..c5bd70a2994617 100644 --- a/Doc/tools/templates/layout.html +++ b/Doc/tools/templates/layout.html @@ -53,10 +53,35 @@ document.addEventListener("readthedocs-addons-data-ready", function(event) { event.detail.initialize(); event.detail.data().then((config) => { - // TODO: add `selected="selected"` to option + // Add some mocked hardcoded versions pointing to the official + // documentation while migrating to Read the Docs. + // These are only for testing purposes. + // TODO: remove them when managing all the versions on Read the Docs, + // since all the "active, built and not hidden" versions will be shown automatically. + let versions = config.versions.active.concat([ + { + slug: "dev (3.13)", + urls: { + documentation: "https://docs.python.org/3.13/", + } + }, + { + slug: "3.12", + urls: { + documentation: "https://docs.python.org/3.12/", + } + }, + { + slug: "3.11", + urls: { + documentation: "https://docs.python.org/3.11/", + } + }, + ]); + const versionSelect = ` - ${ versions.map( - (version) => ` - ` - ).join("\n") } - - `; + // Add some mocked hardcoded versions pointing to the official + // documentation while migrating to Read the Docs. + // These are only for testing purposes. + // TODO: remove them when managing all the versions on Read the Docs, + // since all the "active, built and not hidden" versions will be shown automatically. + let versions = config.versions.active.concat([ + { + slug: "dev (3.13)", + urls: { + documentation: "https://docs.python.org/3.13/", + } + }, + { + slug: "3.12", + urls: { + documentation: "https://docs.python.org/3.12/", + } + }, + { + slug: "3.11", + urls: { + documentation: "https://docs.python.org/3.11/", + } + }, + ]); - let languages = config.projects.translations.concat(config.projects.current); - languages = languages.sort((a, b) => a.language.name.localeCompare(b.language.name)); + const versionSelect = ` + + `; - const languageSelect = ` - - `; + // Prepend the current language to the options on the selector + let languages = config.projects.translations.concat(config.projects.current); + languages = languages.sort((a, b) => a.language.name.localeCompare(b.language.name)); - // Query all the placeholders because there are different ones for Desktop/Mobile - let placeholders = document.querySelectorAll(".version_switcher_placeholder"); - for (placeholder of placeholders) { - placeholder.innerHTML = versionSelect; - let selectElement = placeholder.querySelector("select"); - selectElement.addEventListener("change", onSwitch); - } + const languageSelect = ` + + `; - placeholders = document.querySelectorAll(".language_switcher_placeholder"); - for (placeholder of placeholders) { - placeholder.innerHTML = languageSelect; - let selectElement = placeholder.querySelector("select"); - selectElement.addEventListener("change", onSwitch); - } - }); + // Query all the placeholders because there are different ones for Desktop/Mobile + const versionPlaceholders = document.querySelectorAll(".version_switcher_placeholder"); + for (placeholder of versionPlaceholders) { + placeholder.innerHTML = versionSelect; + let selectElement = placeholder.querySelector("select"); + selectElement.addEventListener("change", onSwitch); + } + + const languagePlaceholders = document.querySelectorAll(".language_switcher_placeholder"); + for (placeholder of languagePlaceholders) { + placeholder.innerHTML = languageSelect; + let selectElement = placeholder.querySelector("select"); + selectElement.addEventListener("change", onSwitch); + } }); {% endblock %}