From 44456497b0fc0e7ac47b0937f6252b6ca049c2ef Mon Sep 17 00:00:00 2001
From: Florian Preinstorfer <site-github@nblock.org>
Date: Fri, 22 Nov 2024 13:16:55 +0100
Subject: [PATCH] Add versioned documentation

Setup mike to provide versioned builds of the documentation.

The goal is to have versioned docs for stable releases (0.23.0, 0.24.0)
and development docs that can progress along with the code. This allows
us to tailor docs to the next upcoming version as we no longer need to
care about diversion between rendered docs and the latest release.

Versions:
* development (alias: unstable) on each push to the main branch
* MAJOR.MINOR.PATCH (alias: stable, latest for the newest version)
  * for each "final" release tag
  * for each push to doc maintenance branches: doc/MAJOR.MINOR.PATCH

The default version should the current stable version. The doc
maintenance branches may be used to update the version specific
documentation when issues arise after a release.
---
 .github/workflows/docs-deploy.yml | 48 ++++++++++++++++++++++++++++
 .github/workflows/docs.yml        | 52 -------------------------------
 docs/requirements.txt             |  1 +
 mkdocs.yml                        |  4 +++
 4 files changed, 53 insertions(+), 52 deletions(-)
 create mode 100644 .github/workflows/docs-deploy.yml
 delete mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
new file mode 100644
index 00000000..b3933548
--- /dev/null
+++ b/.github/workflows/docs-deploy.yml
@@ -0,0 +1,48 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      # Main branch for development docs
+      - main
+
+      # Doc maintenance branches
+      - doc/[0-9]+.[0-9]+.[0-9]+
+    tags:
+      # Stable release tags
+      - v[0-9]+.[0-9]+.[0-9]+
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Setup cache
+        uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - name: Setup dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Configure git
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+      - name: Deploy development docs
+        if: github.ref == 'refs/heads/main'
+        run: mike deploy --push development unstable
+      - name: Deploy stable docs from doc branches
+        if: startsWith(github.ref, 'refs/heads/doc/')
+        run: mike deploy --push ${GITHUB_REF_NAME##*/}
+      - name: Deploy stable docs from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        # This assumes that only newer tags are pushed
+        run: mike deploy --push --update-aliases ${GITHUB_REF_NAME#v} stable latest
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
deleted file mode 100644
index 565841db..00000000
--- a/.github/workflows/docs.yml
+++ /dev/null
@@ -1,52 +0,0 @@
-name: Build documentation
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Install python
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - name: Setup cache
-        uses: actions/cache@v4
-        with:
-          key: ${{ github.ref }}
-          path: .cache
-      - name: Setup dependencies
-        run: pip install -r docs/requirements.txt
-      - name: Build docs
-        run: mkdocs build --strict
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./site
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    permissions:
-      pages: write
-      id-token: write
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Configure Pages
-        uses: actions/configure-pages@v4
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
diff --git a/docs/requirements.txt b/docs/requirements.txt
index d375747b..65174cd4 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
+mike~=2.1
 mkdocs-include-markdown-plugin~=7.1
 mkdocs-macros-plugin~=1.3
 mkdocs-material[imaging]~=9.5
diff --git a/mkdocs.yml b/mkdocs.yml
index cfe76e9c..e28cd593 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -71,6 +71,7 @@ plugins:
   - include-markdown:
   - minify:
       minify_html: true
+  - mike:
   - social: {}
   - redirects:
       redirect_maps:
@@ -90,6 +91,9 @@ plugins:
 
 # Customization
 extra:
+  version:
+    alias: true
+    provider: mike
   annotate:
     json: [.s2]
   social: