Make 'versions' element mandatory

projectgus · projectgus · commit 0421416ae149 · 2020-03-05T10:52:53.000+11:00
diff --git a/README.rst b/README.rst
@@ -28,15 +28,51 @@ Set the following additional config variables in the Sphinx project:
 
 - ``idf_target`` - slug of the IDF target (ie esp32, esp32s2). Optional, but if ``idf_target`` is set then ``idf_targets`` must be set and vice versa. If these two are unset, no "Targets" section is generated in the navigation footer.
 - ``idf_targets`` - Python list with short names of all supported IDF targets (ie ``["esp32", "esp32s2"]``).
-- ``languages`` - Python list with short names of all supported languages (ie ``["en", "zh_CN"]``). If this is unset, no "Languages" section is generated in then navigation footer.
+- ``languages`` - Python list with short names of all supported languages (ie ``["en", "zh_CN"]``). Must be set to at least one language element (the current project's language)
 - ``project_slug`` - short name of the project as a URL slug (ie ``esp-idf``)
 - ``versions_url`` - URL to download the ``versions.js`` file from
 - ``project_homepage`` - URL of the project's main page (GitHub, etc)
 
 Versions file
 ^^^^^^^^^^^^^
 
-TBD
+The file found at the ``versions_url`` location should be a JavaScript file describing all current versions. It should take this form:
+
+.. highlight:: javascript
+
+```
+var DOCUMENTATION_VERSIONS = {
+    "DEFAULTS": { "has_targets": false },
+    "VERSIONS": [
+        { "name": "latest", "has_targets": true },
+        { "name": "v4.0" },
+        { "name": "v3.3.1" },
+        { "name": "v3.3", "old": true  },
+        { "name": "v3.2.3" },
+        { "name": "v3.2.2", "old": true },
+        { "name": "v3.1.6" },
+        { "name": "v3.1.5", "old": true },
+        { "name": "v3.0.9", "old": true },
+        { "name": "v4.0-rc", "pre_release": true },
+        { "name": "v4.0-beta2", "pre_release": true },
+        { "name": "release-v4.1", "pre_release": true },
+        { "name": "release-v4.0", "pre_release": true },
+        { "name": "release-v3.3", "pre_release": true },
+        { "name": "release-v3.2", "pre_release": true },
+        { "name": "release-v3.1", "pre_release": true },
+    ]
+};
+```
+
+.. note:: This file is JavaScript so it can be easily included in a script tag, but it's excpected to contain a single assignment statement which assigns the ``DOCUMENTATION_VERSIONS`` variable to a valid JSON object. Doing any other JavaScript computation in this file is invalid.
+
+Inside the ``DOCUMENTATION_VERSIONS`` object:
+
+- ``VERSIONS`` key is a list of versions, where each version is a JSON object with at minimum a ``name`` key which is the version name "slug", and optionally one or more of the following keys:
+  - ``has_targets`` is true if the URLs for these docs have a target element, ie ``<project>/<language>/<target>/<version>``. False if the URL format is ``<project>/<language>/<version>``. A single project can have some versions which include and some which exclude the target URL component.
+  - ``old`` is true if this version is not current, will be shown in "Old Versions" section under the main versions.
+  - ``pre_release`` is true if this version is a prerelease not a stable release, will be shown in "Prereleases" section under  the main versions
+- ``DEFAULTS`` key contains the default values for any keys which are not supplied in an individual ``VERSIONS`` entries. Just exists to make the file more readable.
 
 
 
diff --git a/sphinx_idf_theme/__init__.py b/sphinx_idf_theme/__init__.py
@@ -29,7 +29,7 @@ def setup(app):
     app.add_config_value('project_homepage', '', 'html')
     app.add_config_value('languages', None, 'html')
 
-    # we expect IDF to also add these, but older version may not
+    # we expect IDF to also add these, but older version may not (and the theme supports non-target-aware docs)
     if "idf_target" not in app.config:
         app.add_config_value('idf_target', None, 'env')
     if "idf_targets" not in app.config:
@@ -46,5 +46,10 @@ def inject_template_context(app, pagename, templatename, context, doctree):
     # expose some IDF-specific config in the html_context dict for the theme
     for key in [ "project_slug", "versions_url", "project_homepage", "languages", "idf_target", "idf_targets", "project" ]:
         context[key] = app.config[key]
+
+    if not app.config.languages:
+        raise RuntimeError("The 'languages' config item needs to be set to a list of supported languages (even if just a single element list)")
+    if not app.config.language:
+        raise RuntimeError("The 'language' config item needs to be set to the language in use")
     if bool(app.config.idf_target) != bool(app.config.idf_targets):
         raise RuntimeError("Either both 'idf_target' and 'idf_targets' variables should be set in Sphinx config, or neither should be set in config.")
diff --git a/sphinx_idf_theme/versions.html b/sphinx_idf_theme/versions.html
@@ -43,14 +43,14 @@
       {% if release == "latest" %}
         <strong>
       {% endif %}
-      <!-- Latest version URL may not be correct depending on whether that version has different language & idf_targets as part of the URL format compared to this version.
+      <!-- Latest version URL may not be correct depending on whether that version has idf_target as part of the URL format compared to this version.
            JavaScript will update it on page load -->
       <dd id="version-latest"><a href="{{ pathto('..', 1) }}/latest/{{ pagename }}.html">latest</a></dd>
       {% if release == "latest" %}
         </strong>
       {% endif %}
 
-      <!-- Stable version URL may not be correct depending on whether that version has different language & idf_targets as part of the URL format compared to this version.
+      <!-- Stable version URL may not be correct depending on whether that version has idf_target as part of the URL format compared to this version.
            JavaScript will update it on page load -->
       <dd id="version-stable"><a href="{{ pathto('..', 1) }}/stable/{{ pagename }}.html">stable</a></dd>
     </dl>
diff --git a/src/idf_embeds.js b/src/idf_embeds.js
@@ -26,23 +26,17 @@ function setupVersions() {
         /* Find the (relative) base URL for this project, finding a sibling URL will be built as follows:
            <project_base_url>/<language>/<idf_target>/<version>
 
-           (Where language and target path elements are optional depending on if the project/version has these.)
+           (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.LANGUAGES) {
-            project_base_url += "/..";
-        }
+        let project_base_url = DOCUMENTATION_OPTIONS.URL_ROOT + "../..";
         if (DOCUMENTATION_OPTIONS.IDF_TARGETS) {
             project_base_url += "/..";
         }
         console.log("project_base_url = " + project_base_url);
 
         /* Given a version from the list, return the URL to link to it */
         function getVersionUrl(v) {
-            let result = project_base_url;
-            if (v.has_languages) {
-                result += "/" + (language || "en");
-            }
+            let result = project_base_url + "/" + language;
             if (v.has_targets) {
                 result += "/" + (idf_target || "esp32");
             }
@@ -58,7 +52,7 @@ function setupVersions() {
             /* Highlight the stable version if that's what we're looking at */
             $( "#version-stable>a" ).wrap("<strong></strong>");
         } else {
-            /* Rewrite the URL for stable to account for languages/targets in that version */
+            /* Rewrite the URL for stable to account for targets (or not) in that particular version */
             stable = jQuery.extend({}, stable); // clone the version object to make the name 'stable'
             stable.name = "stable";
             $( "#version-stable>a" ).attr("href", getVersionUrl(stable));
