Enable switching different versions of documentation

[seisman]

Description of proposed changes

Enable switching different versions of documentation. Adapted from GenericMappingTools/gmt#4110.

Preview:

How to preview/test this PR locally:

# check out this branch
git checkout doc-switcher

# 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

You will see that you can switch from dev to other versions, but can't swich back. That's because the old documentations are static HTML files, and don't include the version_switch.js script.

To enable switching back and forth, we need to manually add the following line in the HTML head part.

<script type="text/javascript" src="/dev/_static/version_switch.js"></script>

This can be done by running the following command in each subdirectory (e.g., in v0.2.0)

find . -name '*.html' -exec sed -i"" '/<\/head>/i<script type="text\/javascript" src="\/dev\/_static\/version_switch.js"><\/script>' {} +

note: the sed command only work for the GNU sed. For macOS users, run gsed instead.

TODO before merging this PR

• Change doc_url from 0.0.0.0:8000 (for local testing) to www.pygmt.org

TODO after merging this PR

• Run the above command to update the old docs in the gh-pages branch
• Each version has a _static/documentation_options.js file. It contains basic settings of the documentation. For old documentations, the VERSION setting is empty, because we didn't set the release variable in conf.py. It will shows the weird latest () instead of latest (v0.2.0). We need to manually update the files of all old versions.

Fixes #609.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

[weiji14]

Awesome comprehensive writeup! Managed to go through the step by step instructions and got this working locally in no time. Only two minor nitpick comments (which you can ignore), otherwise let's get this handy feature merged in (after changing "0.0.0.0:8000" to "www.pygmt.org" of course)!

[weiji14]

I'm not a frontend/javascript expert, and I don't expect you to work on this. But, just pointing out that the dropdown isn't super-accessible. I managed to tab-tab-tab my way to the version changer dropdown (with the benefit of sight), and change to a different version of the documentation by pressing up/down with my arrow keys (only once though, it doesn't seem to allow scrolling through the list of options).

Guess my point here is that we should keep the section at https://www.pygmt.org/v0.2.0/index.html#documentation-for-other-versions for now just for a11y reasons, until we get a good developer that knows this stuff.

[seisman]

Let's open an issue and see if someone with good web knowledge can help us.

[seisman]

The changes are online now, and you can try it at https://www.pygmt.org.

[weiji14]

Yay 🎉! I see you've made the change directly at ae2aee5. Good work 👍