Enable switching different versions of documentation (#621)

* Enable switching different versions of documentation

How to test this PR locally

```
# check out this branch
git checkout doc-switcher
# change doc_url to 0.0.0.0:8000 in doc/_static/version_switcher.js 

# build the documentation
cd doc
make
cd ..

# checkout the gh-pages branch
git checkout gh-pages

# replace the "dev" documentation
rm -r dev
cp -r doc/_build/html dev

# run a simple http server
python -m http.server

# open http://0.0.0.0:8000/dev/ in your web browser
```

Author: seisman

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -13,6 +13,7 @@ assignees: ''
 **Before release**:
 - [ ] Reserve a DOI on [Zenodo](https://zenodo.org) by clicking on "New Version"
 - [ ] Update Changelog
+- [ ] Add a new entry in `doc/_static/version_switch.js` for documentation switcher
 
 **Release**:
 - [ ] Go to [GitHub Release](https://github.com/GenericMappingTools/pygmt/releases) and make a release, this will automatically create a tag too

doc/_static/version_switch.js

@@ -0,0 +1,79 @@
+// 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 = "www.pygmt.org";
+  //var doc_url = "0.0.0.0:8000"; // for local testing only
+  var url_re = new RegExp(doc_url + "\\/(dev|latest|(v\\d+\\.\\d+\\.\\d+))\\/");
+  // List all versions.
+  // Add one entry "version: title" for any minor releases
+  var all_versions = {
+    'latest': 'latest',
+    'dev': 'dev',
+    'v0.2.0': 'v0.2.0',
+    'v0.1.2': 'v0.1.2',
+    'v0.1.1': 'v0.1.1',
+    'v0.1.0': 'v0.1.0',
+    '0.0.1a0': 'v0.0.1a0',
+  };
+
+  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);
+
+    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/_templates/layout.html

@@ -15,6 +15,10 @@
       ga('set', 'anonymizeIp', true);
       ga('send', 'pageview');
     </script>
+
+    <!-- Documentation switcher -->
+    <!-- Point to the *dev* version switcher. This will allow the latest versions to appear on older documentation. -->
+    <script type="text/javascript" src="/dev/_static/version_switch.js"></script>
 {% endblock %}
 
 

doc/conf.py

@@ -103,6 +103,7 @@
     version = "dev"
 else:
     version = __version__
+release = __version__
 
 # These enable substitutions using |variable| in the rst files
 rst_epilog = """