Version switcher provides explicit URLs (#604)

Co-authored-by: Damian Avila <[email protected]>

Author: choldgraf

docs/_static/switcher.json

@@ -1,35 +1,42 @@
 [
   {
     "name": "dev",
-    "version": "latest"
+    "version": "latest",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
   },
   {
     "name": "0.8.0 (stable)",
     "version": "stable",
-    "extra_classes": ["stable"]
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/"
   },
   {
     "name": "0.8.0",
-    "version": "v0.8.0"
+    "version": "v0.8.0",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.8.0/"
   },
   {
     "name": "0.7.2",
-    "version": "v0.7.2"
+    "version": "v0.7.2",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.7.2/"
   },
   {
     "name": "0.6.3",
-    "version": "v0.6.3"
+    "version": "v0.6.3",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.6.3/"
   },
   {
     "name": "0.5.2",
-    "version": "v0.5.2"
+    "version": "v0.5.2",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.5.2/"
   },
   {
     "name": "0.4.3",
-    "version": "v0.4.3"
+    "version": "v0.4.3",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.4.3/"
   },
   {
     "name": "0.3.2",
-    "version": "v0.3.2"
+    "version": "v0.3.2",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.3.2/"
   }
 ]

docs/conf.py

@@ -131,7 +131,6 @@
     # "footer_items": ["copyright", "sphinx-version", ""]
     "switcher": {
         "json_url": json_url,
-        "url_template": "https://pydata-sphinx-theme.readthedocs.io/en/{version}/",
         "version_match": version_match,
     },
 }

docs/user_guide/configuring.rst

@@ -361,8 +361,6 @@ The switcher requires the following configuration steps:
    ``html_theme_options`` dict in ``conf.py``. ``switcher`` should have 3 keys:
 
    - ``json_url``: the persistent location of the JSON file described above.
-   - ``url_template``: a template string used to generate the correct URLs for
-     the different documentation versions.
    - ``version_match``: a string stating the version of the documentation that
      is currently being browsed.
 
@@ -380,14 +378,11 @@ First, write a JSON file stating which versions of your docs will be listed in
 the switcher's dropdown menu. That file should contain a list of entries that
 each can have the following fields:
 
-- ``version``: a version string. This will be inserted into
-  ``switcher['url_template']`` to create the links to other docs versions, and
-  also checked against ``switcher['version_match']`` to provide styling to the
-  switcher.
+- ``version``: a version string. This is checked against
+  ``switcher['version_match']`` to provide styling to the switcher.
+- ``url``: the URL for this version.
 - ``name``: an optional name to display in the switcher dropdown instead of the
   version string (e.g., "latest", "stable", "dev", etc).
-- ``url``: an optional URL. If provided, it links the version to ``url``
-  instead of ``switcher['url_template']``.
 
 Here is an example JSON file:
 
@@ -396,13 +391,16 @@ Here is an example JSON file:
     [
         {
             "name": "v2.1 (stable)",
-            "version": "2.1"
+            "version": "2.1",
+            "url": "https://mysite.org/en/2.1/index.html"
         },
         {
             "version": "2.1rc1",
+            "url": "https://mysite.org/en/2.1rc1/index.html"
         },
         {
-            "version": "2.0"
+            "version": "2.0",
+            "url": "https://mysite.org/en/2.0/index.html"
         },
         {
             "version": "1.0",
@@ -461,28 +459,6 @@ a few different ways:
       }
 
 
-Configure ``switcher['url_template']``
---------------------------------------
-
-The switcher's links to other versions of your docs are made by combining the
-*version strings* from the JSON file with a *template string* you provide in
-``switcher['url_template']``. The template string must contain a placeholder
-``{version}`` and otherwise be a fully-resolved URL. For example:
-
-.. code:: python
-
-    html_theme_options = {
-        ...,
-        "switcher": {
-            "url_template": "https://mysite.org/en/version-{version}/",
-        }
-    }
-
-The example above will result in a link to
-``https://mysite.org/en/version-1.0/`` for the JSON entry for version
-``"1.0"``.
-
-
 Configure ``switcher['version_match']``
 ---------------------------------------
 

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html

@@ -14,13 +14,6 @@
 -->
 
 <script type="text/javascript">
-// Construct the target URL from the JSON components
-function buildURL(entry) {
-    var template = "{{ theme_switcher.get('url_template') }}";  // supplied by jinja
-    template = template.replace("{version}", entry.version);
-    return template;
-}
-
 // Check if corresponding page path exists in other version of docs
 // and, if so, go there instead of the homepage of the other docs version
 function checkPageExistsAndRedirect(event) {
@@ -56,11 +49,6 @@
             const node = document.createElement("a");
             node.setAttribute("class", "list-group-item list-group-item-action py-1");
             node.textContent = `${entry.name}`;
-            // get the base URL for that doc version, add the current page's
-            // path to it, and set as `href`
-            if (!("url" in entry)) {
-                entry.url = buildURL(entry);
-            }
             node.setAttribute("href", `${entry.url}${currentFilePath}`);
             // on click, AJAX calls will check if the linked page exists before
             // trying to redirect, and if not, will redirect to the homepage