ci: publish versioned docs

.github/workflows/publish-docs.yaml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - main
+    tags:
+      - '**'
 
 permissions:
   contents: write
@@ -38,6 +40,19 @@ jobs:
         if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
         run: poetry install --no-interaction --only docs
 
-      # deploy github pages
-      - name: Deploy GitHub Pages
-        run: poetry run mkdocs gh-deploy --force
+      # deploy github pages (dev)
+      - name: Deploy GitHub Pages (dev)
+        if: "github.ref == 'refs/heads/main'"
+        run: poetry run mike deploy -b gh-pages dev --push
+
+      # deploy github pages (release)
+      - if: "github.ref == startsWith(github.ref, 'refs/tags/')"
+        id: check-version
+        uses: samuelcolvin/[email protected]
+        with:
+          version_file_path: 'ecologits/__init__.py'
+          skip_env_check: true
+
+      - name: Deploy GitHub Pages (release)
+        if: "github.ref == startsWith(github.ref, 'refs/tags/')"
+        run: poetry run mike deploy -b gh-pages ${{ steps.check-version.outputs.VERSION_MAJOR_MINOR }} latest --update-aliases --push

mkdocs.yml

@@ -97,6 +97,9 @@ plugins:
               ignore_init_summary: yes
             merge_init_into_class: yes
             inherited_members: true
+  - mike:
+      alias_type: symlink
+      canonical_version: latest
 
 
 

pyproject.toml

@@ -81,6 +81,7 @@ mkdocstrings = { version = "^0.25.0", extras = ["python"] }
 mkdocs-gen-files = "^0.5.0"
 mkdocs-autorefs = "^1.0.1"
 mkdocs-literate-nav = "^0.6.1"
+mike = "^2.1.2"
 
 
 [pytest]