docs: introduce mike for versioned documentation

Author: d-biehl

hatch.toml

@@ -90,7 +90,7 @@ all = ["style", "typing"]
 
 [envs.pages]
 #detached = true
-dependencies = [
+extra-dependencies = [
   "mkdocs>=1.4.2",
   "mkdocs-material",
   # Plugins
@@ -105,10 +105,13 @@ dependencies = [
   "pymdown-extensions~=9.6.0",
   # Necessary for syntax highlighting in code blocks
   "pygments",
+  "mike",
 ]
 
 [envs.pages.scripts]
 build = ["mkdocs build"]
+deploy = ["python scripts/deploy_docs.py"]
+
 
 [envs.build]
 detached = true

mkdocs.yml

@@ -11,6 +11,7 @@ copyright: >
 
 theme:
   name: material
+  custom_dir: overrides
   language: en
   icon:
     repo: fontawesome/brands/github
@@ -107,6 +108,13 @@ extra:
       - accept
       - reject
       - manage
+  version:
+    provider: mike
+    default: latest
+
+plugins:
+  - mike:
+      canonical_version: latest
 
 extra_css:
   - stylesheets/extra.css
@@ -116,5 +124,5 @@ nav:
   - Features: features.md
   - Installation: installation.md
   - CLI:
-    - About: cli/about.md
-    - Reference: cli/reference.md
+      - About: cli/about.md
+      - Reference: cli/reference.md

overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+You're not viewing the latest version.
+<a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+</a>
+{% endblock %}

scripts/deploy_docs.py

@@ -0,0 +1,24 @@
+from subprocess import run
+
+from scripts.tools import get_current_version_from_git
+
+
+def main() -> None:
+    version = get_current_version_from_git()
+    alias = "latest"
+
+    if version.prerelease:
+        version = version.next_minor()
+        alias = "dev"
+
+    version.major, version.minor
+
+    run(
+        "mike deploy --push --update-aliases --rebase --force "
+        f'--title "v{version.major}.{version.minor}.x ({alias})" {version.major}.{version.minor} {alias}',
+        shell=True,
+    ).check_returncode()
+
+
+if __name__ == "__main__":
+    main()