docs: use mike to document all versions

.github/workflows/docs.yml

@@ -14,15 +14,6 @@ jobs:
       uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
 
     - run: pip install hatch
-    - run: hatch run docs:export-deps > doc_requirements.txt
-
-    - name: Deploy docs
-      uses: mhausenblas/mkdocs-deploy-gh-pages@d77dd03172e96abbcdb081d8c948224762033653 # 1.26
-        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          #CUSTOM_DOMAIN: optionaldomain.com
-          #CONFIG_FILE: folder/mkdocs.yml
-          #EXTRA_PACKAGES: build-base
-          # GITHUB_DOMAIN: github.myenterprise.com
-        REQUIREMENTS: doc_requirements.txt
+    - run: git fetch origin gh-pages --depth=1
+    - run: hatch version
+    - run: hatch run docs:mike deploy --push development

.github/workflows/test_docs.yml

@@ -2,17 +2,21 @@ name: test docs
 on:
   pull_request:
   push:
-    branches: [main]
+    branches: [main, docs-versioning]
 
 jobs:
   build:
-    name: build docs
+    name: Deploy docs
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
-    - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
-      with:
-        python-version: '3.12'
-        architecture: x64
+    - name: Checkout main
+      uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+
     - run: pip install hatch
-    - run: hatch run docs:build
+    - run: git fetch origin gh-pages --depth=1
+    - run: hatch version
+    - run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git fetch origin gh-pages --depth=1
+        hatch run docs:mike deploy --push development

docs/theme/main.html

@@ -1,5 +1,12 @@
 {% 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 %}
+
 {% block announce %}
 
   {{ super() }}

mkdocs.yml

@@ -80,9 +80,15 @@ plugins:
     ansi: required
 - replace-url
 
+
 extra:
   social:
   - icon: fontawesome/brands/x-twitter
     link: https://x.com/15r10nk
   - icon: fontawesome/brands/mastodon
     link: https://fosstodon.org/@15r10nk
+  version:
+    provider: mike
+    default:
+    - latest
+    - development

pyproject.toml

@@ -87,6 +87,7 @@ dependencies = [
   "markdown-exec[ansi]>=1.8.0",
   "mkdocs>=1.4.2",
   "mkdocs-material[imaging]>=9.5.17",
+  "mike",
   "mkdocstrings[python]>=0.19.0",
   "replace-url @ {root:uri}/docs/plugins",
   "pytest",