Use mkdocs extension mike to build versioned docs

.github/workflows/documentation-deploy-development.yml

@@ -0,0 +1,40 @@
+name: Build/Publish Latest Develop Docs
+
+permissions: write-all
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+    - main
+  workflow_dispatch:
+
+jobs:
+  build-docs-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.13
+
+      - name: Install dependencies
+        run: |
+          pip install ".[doc]"
+      - name: Setup Docs Deploy user
+        run: |
+          git config --global user.name "Docs Deploy"
+          git config --global user.email "docs.deploy@example.co.uk"
+      - name: Deploy mkdocs on GitHub Pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG_NAME=${{ github.ref_name }}
+          MAJ_MIN_VERSION=${TAG_NAME%/*}
+          echo $MAJ_MIN_VERSION
+          mike deploy --push develop

.github/workflows/documentation-deploy.yml → .github/workflows/documentation-deploy-release.yml

@@ -1,4 +1,4 @@
-name: documentation-deploy
+name: Build/Publish Latest Release Docs
 
 permissions: write-all
 
@@ -11,17 +11,24 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-
+        with:
+          fetch-depth: 0
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: 3.13
 
       - name: Install dependencies
         run: |
-          pip install ".[doc]" 
+          pip install ".[doc]"
+      - name: Setup Docs Deploy user
+        run: |
+          git config --global user.name "Docs Deploy"
+          git config --global user.email "docs.deploy@example.co.uk"
       - name: Deploy mkdocs on GitHub Pages
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          mkdocs gh-deploy --force
+          TAG_NAME=${{ github.event.release.tag_name }}
+          MAJ_MIN_VERSION=${TAG_NAME%.*}
+          mike deploy --push --update-aliases $MAJ_MIN_VERSION latest

.gitignore

@@ -15,6 +15,7 @@ coverage.xml
 .tox
 
 docs/_build
+site
 
 # ide
 .idea

README.dev.md

@@ -117,6 +117,10 @@ mkdocs serve
 
 This will return a URL (e.g. `http://127.0.0.1:8000/mibitrans/`) where the docs site can be viewed.
 
+Note that this will only create the "non-versioned" documentation, which should be fine for testing changes to the docs.
+The versioned documentation is created using the python utility called [mike](https://github.com/jimporter/mike?tab=readme-ov-file#mike) and its corresponding [mkdocs integration](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/).
+In general it should not be necessary to test this, but if necessary, use [the mike documentation](https://github.com/jimporter/mike?tab=readme-ov-file#viewing-your-docs) to inspect locally.
+
 ## Versioning
 
 Bumping the version across all files is done with [bump-my-version](https://github.com/callowayproject/bump-my-version), e.g.

mkdocs.yml

@@ -99,3 +99,7 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/MiBiPreT/mibitrans
+  version:
+    provider: mike
+    default: latest
+    alias: true

pyproject.toml

@@ -84,6 +84,7 @@ doc = [
     "mkdocstrings[python] ==0.27.0",
     "mdx-include >=1.4.1",
     "mkdocs-markdownextradata-plugin >=0.2.5",
+    "mike >=2.1.3"
 ]
 
 [project.urls]