From c51ffd7166273499400e2dbfd98298bf123f66f5 Mon Sep 17 00:00:00 2001
From: Sam Vente <savente93@gmail.com>
Date: Thu, 27 Jul 2023 07:00:42 +0000
Subject: [PATCH] Add version switch to docs (#457)

---
 docs/_static/switcher.json | 39 ++++++++++++++++++++++++++++++++++++++
 docs/changelog.rst         |  2 +-
 docs/conf.py               | 10 ++++++++--
 docs/dev/contributing.rst  | 12 ++++++------
 4 files changed, 54 insertions(+), 9 deletions(-)
 create mode 100644 docs/_static/switcher.json

diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json
new file mode 100644
index 000000000..79df63741
--- /dev/null
+++ b/docs/_static/switcher.json
@@ -0,0 +1,39 @@
+[
+
+  {
+    "name":"v0.5.0",
+    "version":"0.5.0",
+    "url":"https://deltares.github.io/hydromt/v0.5.0/"
+
+  },
+  {
+    "name":"v0.6.0",
+    "version":"0.6.0",
+    "url":"https://deltares.github.io/hydromt/v0.6.0/"
+
+  },
+  {
+    "name":"v0.7.0",
+    "version":"0.7.0",
+    "url":"https://deltares.github.io/hydromt/v0.7.0/"
+
+  },
+  {
+    "name":"v0.7.1",
+    "version":"0.7.1",
+    "url":"https://deltares.github.io/hydromt/v0.7.1/"
+
+  },
+  {
+    "name":"v0.8.0",
+    "version":"0.8.0",
+    "url":"https://deltares.github.io/hydromt/v0.8.0/"
+
+  },
+  {
+    "name":"latest",
+    "version":"latest",
+    "url":"https://deltares.github.io/hydromt/latest/"
+
+  }
+]
diff --git a/docs/changelog.rst b/docs/changelog.rst
index d8a07cbfb..670cfdbb5 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -11,7 +11,7 @@ Unreleased
 
 Added
 -----
--
+- docs now include a dropdown for selecting older versions of the docs. (#457)
 
 Changed
 -------
diff --git a/docs/conf.py b/docs/conf.py
index 25d880d91..4242fa424 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -234,6 +234,8 @@ def clean_str(s):
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
+bare_version = hydromt.__version__
+doc_version = bare_version[: bare_version.find("dev") - 1]
 html_static_path = ["_static"]
 html_css_files = ["theme-deltares.css"]
 html_theme_options = {
@@ -257,14 +259,18 @@ def clean_str(s):
     "logo": {
         "text": "HydroMT Core",
     },
-    "navbar_end": ["navbar-icon-links"],  # remove dark mode switch
+    "navbar_end": ["navbar-icon-links", "version-switcher"],  # remove dark mode switch
+    "switcher": {
+        "json_url": "https://raw.githubusercontent.com/Deltares/hydromt/gh-pages/switcher.json",
+        "version_match": doc_version,
+    },
 }
 
 html_context = {
     "github_url": "https://github.com",  # or your GitHub Enterprise interprise
     "github_user": "Deltares",
     "github_repo": "hydromt",
-    "github_version": "main",  # FIXME
+    "github_version": "main",
     "doc_path": "docs",
     "default_mode": "light",
 }
diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst
index b192f0ba9..3c14bef11 100644
--- a/docs/dev/contributing.rst
+++ b/docs/dev/contributing.rst
@@ -425,15 +425,15 @@ Creating a release
 1. Create a new branch with the name "release/<version>" where <version> is the version number, e.g. v0.7.0
 2. Bump the version number (without "v"!) in the __init__.py, check and update the docs/changelog.rst file and add a short summary to the changelog for this version.
    Check if all dependencies in the toml are up to date. Commit all changes
-3. Create a tag using `git tag <version>`, e.g. git tag v0.7.0
-4. Push your changes to github. To include the tag do `git push origin <version>`. This should trigger a test release to test.pypi.org
-5. If all tests and the test release have succeeded, merge de branch to main.
-6. Create a new release on github under https://github.com/Deltares/hydromt/releases.
+3. Create a new documentation version in the `docs/switcher.json` that has the same structure as the other version entries. Please make sure the list stays sorted as this represents the ordering of the menu.
+4. Create a tag using `git tag <version>`, e.g. git tag v0.7.0
+5. Push your changes to github. To include the tag do `git push origin <version>`. This should trigger a test release to test.pypi.org
+6. If all tests and the test release have succeeded, merge de branch to main.
+7. Create a new release on github under https://github.com/Deltares/hydromt/releases.
    Use the "generate release notes" button and copy the content of the changelog for this version on top of the release notes. This should trigger the release to PyPi.
-7. The new PyPi package will trigger a new PR to the `HydroMT feedstock repos of conda-forge <https://github.com/conda-forge/hydromt-feedstock>`_.
+8. The new PyPi package will trigger a new PR to the `HydroMT feedstock repos of conda-forge <https://github.com/conda-forge/hydromt-feedstock>`_.
    Check if all dependencies are up to date and modify the PR if necessary. Merge the PR to release the new version on conda-forge.
 
-
 .. NOTE::
 
   In the next PR that get's merged into main, the version numbers in __init__.py and the changelog should be changed to the next release with ".dev" postfix.