Docs: build doc with new layout for target and version select

.gitlab-ci.yml

@@ -58,7 +58,7 @@ variables:
   CI_AUTO_TEST_SCRIPT_REPO_BRANCH: "ci/v3.1"
 
   # Versioned esp-idf-doc env image to use for all document building jobs
-  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v8"
+  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v9-4a53df18"
 
 .setup_tools_unless_target_test: &setup_tools_unless_target_test |
   if [[ -n "$IDF_DONT_USE_MIRRORS" ]]; then

docs/_static/js/version_table.js

@@ -0,0 +1,54 @@
+$(document).ready(function() {
+
+    let version = DOCUMENTATION_OPTIONS.VERSION;
+    let language = DOCUMENTATION_OPTIONS.LANGUAGE;
+    let idf_target = DOCUMENTATION_OPTIONS.IDF_TARGET;
+    let pagename = DOCUMENTATION_OPTIONS.PAGENAME + ".html";
+
+    let defaults = DOCUMENTATION_VERSIONS.DEFAULTS;
+    let versions = DOCUMENTATION_VERSIONS.VERSIONS;
+
+    /* Apply the defaults to each version, where needed */
+    for (let i = 0; i < versions.length; i++) {
+        let v = versions[i];
+        for (let d in defaults) {
+            if (!(d in v)) {
+                v[d] = defaults[d];
+            }
+        }
+    }
+
+    /* Find the (relative) base URL for this project, finding a sibling URL will be built as follows:
+    <project_base_url>/<language>/<version>/<idf_target>
+
+    (Where 'idf_target' path element are optional depending on if the project has multiple target support)
+    */
+    let project_base_url = DOCUMENTATION_OPTIONS.URL_ROOT + "../..";
+    if (DOCUMENTATION_OPTIONS.IDF_TARGETS) {
+        project_base_url += "/..";
+    }
+
+    /* Given a version from the list, return the URL to link to it */
+    function getVersionUrl(v) {
+        let result = project_base_url + "/" + language + "/" + v.name;
+        if (v.has_targets) {
+            result += "/" + (idf_target || "esp32");
+        }
+
+        return result + "/";
+    };
+
+    old_ver_list = "";
+
+    for (let i = 0; i < versions.length; i++) {
+        let v = versions[i];
+        let url = getVersionUrl(v);
+
+        if (v.old) {
+            old_ver_list += "<li><a href=\"" + url + "\">" + v.name + "</li>";
+        }
+
+    }
+
+    $( "#version_list" ).append(old_ver_list);
+});

docs/_static/version_table.html

@@ -0,0 +1,7 @@
+
+<version_table>
+    <script src="_static/js/version_table.js"></script>
+    <ul id="version_list">
+
+    </ul>
+</version_table>

docs/en/index.rst

@@ -6,7 +6,7 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
 
 .. only:: html
 
-    This document describes using ESP-IDF with the {IDF_TARGET_NAME} SoC. To switch to a different SoC target, click "Switch Version" in the bottom left.
+    This document describes using ESP-IDF with the {IDF_TARGET_NAME} SoC. To switch to a different SoC target, choose target from the dropdown in the upper left.
 
 .. only:: latex
 

docs/en/languages.rst

@@ -8,9 +8,9 @@ The ESP-IDF Programming Manual is now available in two languages. Please refer t
 - English/英文
 - Chinese/中文
 
-You can easily change from one language to another by the panel on the sidebar like below. Just click on the **Read the Docs** title button on the left-bottom corner if it is folded.
+You can easily change from one language to another by clicking the language link you can find at the top of every document that has a translation.
 
 如下图所示，你可使用边栏的面板进行语言的切换。如果该面板被折叠，点击左下角 **Read the Docs** 标题按钮来显示它。
 
-.. image:: /../_static/choose_version.png
+.. image:: /../_static/choose_language.png
 

docs/en/versions.rst

@@ -21,9 +21,17 @@ https://docs.espressif.com/projects/esp-idf/en/latest/
 
 The full history of releases can be found on the GitHub repository `Releases page`_. There you can find release notes, links to each version of the documentation, and instructions for obtaining each version.
 
-Another place to find documentation for all releases is the documentation page, where you can go to the bottom-left corner and click the versions dropup (a bar with a small triangle). You can also use this dropup to switch between versions of the documentation.
+.. only:: html
+
+    Another place to find documentation for all current releases is the documentation page, where you can go to the upper-left corner and click the version dropdown (between the target dropdown and the search bar). You can also use this dropdown to switch between versions of the documentation.
+
+    .. image:: /../_static/choose_version.png
+
+    Documentation for older versions are also still available:
+
+    .. raw:: html
+        :file: ../_static/version_table.html
 
-.. image:: /../_static/choose_version.png
 
 
 Which Version Should I Start With?

docs/requirements.txt

@@ -19,4 +19,4 @@ nwdiag==2.0.0
 recommonmark
 future>=0.16.0 # for ../tools/gen_esp_err_to_name.py
 sphinx_selective_exclude==1.0.3
-sphinx_idf_theme==0.2
+sphinx_idf_theme==0.2.2