From e9167f864ef61b6564d905ef75310d05d48eda79 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 17 Sep 2020 02:00:13 -0400 Subject: [PATCH 1/3] Enable switching different versions of documenation How to test this PR: ``` git checkout doc-switcher cd doc make cd .. git checkout gh-pages rm -r dev cp -r doc/_build/html dev python -m http.server ``` --- .github/ISSUE_TEMPLATE/release_checklist.md | 1 + doc/_static/version_switch.js | 78 +++++++++++++++++++++ doc/_templates/layout.html | 4 ++ doc/conf.py | 1 + 4 files changed, 84 insertions(+) create mode 100644 doc/_static/version_switch.js diff --git a/.github/ISSUE_TEMPLATE/release_checklist.md b/.github/ISSUE_TEMPLATE/release_checklist.md index d9c9b2de597..0043fa7006c 100644 --- a/.github/ISSUE_TEMPLATE/release_checklist.md +++ b/.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 diff --git a/doc/_static/version_switch.js b/doc/_static/version_switch.js new file mode 100644 index 00000000000..7904388c0f3 --- /dev/null +++ b/doc/_static/version_switch.js @@ -0,0 +1,78 @@ +// 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', + }; + + function build_select(current_version, current_release) { + var buf = [''); + 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); + } + }); +})(); diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 3de7b40dee3..eb0656de46a 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -15,6 +15,10 @@ ga('set', 'anonymizeIp', true); ga('send', 'pageview'); + + + + {% endblock %} diff --git a/doc/conf.py b/doc/conf.py index 2d878adee1f..feba6168b8d 100644 --- a/doc/conf.py +++ b/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 = """ From 882394fd367a9719784f77b304342a282cb98a01 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 20 Sep 2020 10:15:25 -0400 Subject: [PATCH 2/3] Also show version 0.0.1a0 --- doc/_static/version_switch.js | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/_static/version_switch.js b/doc/_static/version_switch.js index 7904388c0f3..39d0a120711 100644 --- a/doc/_static/version_switch.js +++ b/doc/_static/version_switch.js @@ -16,6 +16,7 @@ '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) { From 7def8d8905b471f81f5ab5f3622524c3c674a8dd Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 20 Sep 2020 16:54:33 -0400 Subject: [PATCH 3/3] change doc_url to www.pygmt.org --- doc/_static/version_switch.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/_static/version_switch.js b/doc/_static/version_switch.js index 39d0a120711..b61756ae60f 100644 --- a/doc/_static/version_switch.js +++ b/doc/_static/version_switch.js @@ -4,8 +4,8 @@ (function() { 'use strict'; - //var doc_url = "www.pygmt.org"; - var doc_url = "0.0.0.0:8000"; // for local testing only + 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