feat: add versioned docs support (#224)

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

.docs/RELEASE.md

@@ -23,3 +23,17 @@ Release notes for the `main` branch lives in [main.md](../.release-notes/main.md
 Make sure it is up to date and rename the file to the version being released.
 
 You can then copy [_template.md](../.release-notes/_template.md) to [main.md](../.release-notes/main.md) for the next release.
+
+## Publish documentation
+
+Publishing the documentation for a release is decoupled from cutting a release.
+
+To publish the documentation push a tag to the GitHub repository (begining with `docs-v`).
+
+```shell
+VERSION="v0.1.0"
+TAG=docs-$VERSION
+
+git tag $TAG -m "tag $TAG" -a
+git push origin $TAG
+```

.github/workflows/deploy.yaml → .github/workflows/docs-main.yaml

@@ -1,6 +1,6 @@
 # yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
 
-name: Deploy
+name: Dev docs
 
 permissions: {}
 
@@ -15,9 +15,9 @@ concurrency:
 
 jobs:
   docs:
+    runs-on: ubuntu-latest
     permissions:
       contents: write
-    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
@@ -32,4 +32,7 @@ jobs:
       - name: Deploy site
         run: |
           set -e
-          mkdocs gh-deploy -f ./website/mkdocs.yaml --force
+          git fetch origin gh-pages --depth=1
+          git config user.name ci-bot
+          git config user.email ci-bot@example.com
+          mike deploy -F ./website/mkdocs.yaml --push --update-aliases main dev

.github/workflows/docs-release.yaml

@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Release docs
+
+permissions: {}
+
+on:
+  push:
+    tags:
+      - 'docs-v*'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Parse semver string
+        id: semver 
+        uses: booxmedialtd/ws-action-parse-semver@7784200024d6b3fc01253e617ec0168daf603de3 # v1.4.7
+        with:
+          input_string: ${{ github.ref_name }}
+          version_extractor_regex: '^docs-v(.*)$'
+      - name: Checkout
+        if: ${{ steps.semver.outputs.prerelease == '' }}
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        if: ${{ steps.semver.outputs.prerelease == '' }}
+        with:
+          go-version-file: go.mod
+          cache-dependency-path: go.sum
+      - name: Build site
+        if: ${{ steps.semver.outputs.prerelease == '' }}
+        run: |
+          set -e
+          make codegen-mkdocs
+      - name: Deploy site
+        if: ${{ steps.semver.outputs.prerelease == '' }}
+        run: |
+          set -e
+          git fetch origin gh-pages --depth=1
+          git config user.name ci-bot
+          git config user.email ci-bot@example.com
+          mike deploy -F ./website/mkdocs.yaml --push --update-aliases ${{ steps.semver.outputs.fullversion }} latest

.release-notes/_template.md

@@ -15,5 +15,7 @@ Release notes for `TODO`.
 
 ## :wrench: Fixes :wrench:
 
+## :books: Docs :books:
+
 ## :guitar: Misc :guitar:
 -->

.release-notes/main.md

@@ -17,3 +17,7 @@ Release notes for `TODO`.
 
 ## :guitar: Misc :guitar:
 -->
+
+## :books: Docs :books:
+
+- Added multi version docs support

Makefile

@@ -241,7 +241,8 @@ codegen-docs: codegen-api-docs codegen-cli-docs codegen-jp-docs codegen-catalog
 codegen-mkdocs: codegen-docs ## Generate mkdocs website
 	@echo Generate mkdocs website... >&2
 	@$(PIP) install mkdocs
-	@$(PIP) install -U mkdocs-material mkdocs-redirects mkdocs-minify-plugin mkdocs-include-markdown-plugin lunr mkdocs-rss-plugin
+	@$(PIP) install --upgrade pip
+	@$(PIP) install -U mkdocs-material mkdocs-redirects mkdocs-minify-plugin mkdocs-include-markdown-plugin lunr mkdocs-rss-plugin mike
 	@mkdocs build -f ./website/mkdocs.yaml
 
 .PHONY: codegen-schemas-openapi
@@ -310,6 +311,18 @@ verify-codegen: codegen ## Verify all generated code and docs are up to date
 	@echo 'To correct this, locally run "make codegen", commit the changes, and re-run tests.' >&2
 	@git diff --quiet --exit-code -- .
 
+##########
+# MKDOCS #
+##########
+
+.PHONY: mkdocs-serve
+mkdocs-serve: ## Generate and serve mkdocs website
+	@echo Generate and servemkdocs website... >&2
+	@$(PIP) install mkdocs
+	@$(PIP) install --upgrade pip
+	@$(PIP) install -U mkdocs-material mkdocs-redirects mkdocs-minify-plugin mkdocs-include-markdown-plugin lunr mkdocs-rss-plugin mike
+	@mkdocs serve -f ./website/mkdocs.yaml
+
 ########
 # TEST #
 ########

website/mkdocs.base.yaml

@@ -20,6 +20,11 @@ strict: true
 extra_css:
 - static/extra.css
 
+# version
+extra:
+  version:
+    provider: mike
+
 theme:
   name: material
   custom_dir: docs/overrides