docs: Enable switching different versions (#4110) (#4111)

Co-authored-by: Dongdong Tian <[email protected]>

Author: github-actions[bot]

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -26,6 +26,7 @@ assignees: ''
 - [ ] update changelog
 - [ ] update INSTALL.md
 - [ ] check if there are any warnings when build the documentation
+- [ ] add one new entry in `doc/rst/_static/version_switch.js` if it's a minor release
 - [ ] check/set values in `cmake/ConfigDefault.cmake`
     - [ ] `GMT_VERSION_YEAR` is current year
     - [ ] `GMT_PACKAGE_VERSION_*` is correctly set

doc/rst/_static/version_switch.js

@@ -0,0 +1,81 @@
+// Copyright 2013 PSF. Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+// File originates from the cpython source found in Doc/tools/sphinxext/static/version_switch.js
+
+(function() {
+  'use strict';
+
+  var doc_url = "docs.generic-mapping-tools.org";
+  // var doc_url = "0.0.0.0:8000"; // for local testing only
+  var url_re = new RegExp(doc_url + "\\/(dev|latest|(\\d+\\.\\d+))\\/");
+  // List all versions.
+  // Add one entry "version: title" for any minor releases
+  var all_versions = {
+    'latest': 'latest',
+    'dev': 'dev',
+    '6.1': '6.1',
+    '6.0': '6.0',
+    '5.4': '5.4',
+    '4.5': '4',
+  };
+
+  function build_select(current_version, current_release) {
+    var buf = ['<select>'];
+
+    $.each(all_versions, function(version, title) {
+      buf.push('<option value="' + version + '"');
+      if (version == current_version) {
+        buf.push(' selected="selected">');
+        if (version == "latest" || version == "dev") {
+          buf.push(title + ' (' + current_release + ')');
+        } else {
+          buf.push(current_version);
+        }
+      } else {
+        buf.push('>' + title);
+      }
+      buf.push('</option>');
+    });
+
+    buf.push('</select>');
+    return buf.join('');
+  }
+
+  function patch_url(url, new_version) {
+    return url.replace(url_re, doc_url + '/' + new_version + '/');
+  }
+
+  function on_switch() {
+    var selected = $(this).children('option:selected').attr('value');
+
+    var url = window.location.href,
+        new_url = patch_url(url, selected);
+    console.log("OK");
+    console.log(new_url);
+    console.log(url);
+
+    if (new_url != url) {
+      // check beforehand if url exists, else redirect to version's start page
+      $.ajax({
+        url: new_url,
+        success: function() {
+           window.location.href = new_url;
+        },
+        error: function() {
+            window.location.href = 'http://' + doc_url + '/' + selected;
+        }
+      });
+    }
+  }
+
+  $(document).ready(function() {
+    var match = url_re.exec(window.location.href);
+    if (match) {
+      var release = DOCUMENTATION_OPTIONS.VERSION;
+      var version = match[1];
+      var select = build_select(version, release);
+      $('.version_switch_note').html('Or, select a version from the drop-down menu above.');
+      $('.version').html(select);
+      $('.version select').bind('change', on_switch);
+    }
+  });
+})();

doc/rst/_templates/layout.html

@@ -1,6 +1,15 @@
 {# Import the theme's layout. #}
 {% extends "!layout.html" %}
 
+{%- block extrahead %}
+{# Enable versions switch #}
+{% if enable_versions_switch %}
+  <!-- Point to the *latest* version switcher. This will allow the latest versions to appear on older documentation. -->
+  <script type="text/javascript" src="/latest/_static/version_switch.js"></script>
+{% endif %}
+{% endblock %}
+
+
 {% block menu %}
     {{ super() }}
 

doc/rst/conf.py.in

@@ -65,7 +65,9 @@ html_context = {
     "github_repo": "gmt",
     "github_version": github_version,
     "theme_vcs_pageview_mode": "edit",
-    "conf_py_path": "/doc/rst/source/"
+    "conf_py_path": "/doc/rst/source/",
+    # Enable versions switch on Azure Pipelines.
+    "enable_versions_switch": True if os.getenv("BUILD_SOURCEBRANCHNAME") else False,
 }
 # favicon of the docs
 html_favicon = "_static/favicon.png"