Set up version-based documentation with mike

.github/workflows/doc_deploy.yml

@@ -17,12 +17,26 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - name: Fetch gh-pages branch
+        run: git fetch origin gh-pages --depth=1
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
       - name: Install dependencies
         run: |
-          python -m pip install .[docs] 
-      - name: Deploy docs
-        run: mkdocs gh-deploy --force
+          python -m pip install .[docs]
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Determine docs version
+        id: docs_version
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          VERSION=$(echo "$TAG" | sed -E 's/^v?([0-9]+\.[0-9]+).*/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Deploy versioned docs
+        run: |
+          mike deploy --push --update-aliases ${{ steps.docs_version.outputs.version }} latest
+          mike set-default --push latest

pyproject.toml

@@ -38,6 +38,16 @@ classifiers=[
     'Programming Language :: Python :: 3.12',
 ]
 
+[project.optional-dependencies]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-jupyter",
+    "mkdocstrings[python]",
+    "mkdocs-gen-files",
+    "mike",
+]
+
 [dependency-groups]
 dev = [
     "pytest",
@@ -53,6 +63,7 @@ docs = [
     "mkdocs-jupyter",
     "mkdocstrings[python]",
     "mkdocs-gen-files",
+    "mike",
 ]
 demo = [
     "jupyterlab",