From 4d15fc94c63215c58c4ed37ff974bfba55441b22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?= Date: Fri, 24 Nov 2023 17:10:19 +0100 Subject: [PATCH] feat: add versioned docs support (#224) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Charles-Edouard Brétéché --- .docs/RELEASE.md | 14 ++++++ .../workflows/{deploy.yaml => docs-main.yaml} | 9 ++-- .github/workflows/docs-release.yaml | 44 +++++++++++++++++++ .release-notes/_template.md | 2 + .release-notes/main.md | 4 ++ Makefile | 15 ++++++- website/mkdocs.base.yaml | 5 +++ 7 files changed, 89 insertions(+), 4 deletions(-) rename .github/workflows/{deploy.yaml => docs-main.yaml} (76%) create mode 100644 .github/workflows/docs-release.yaml diff --git a/.docs/RELEASE.md b/.docs/RELEASE.md index b5e2de53..d8f31971 100644 --- a/.docs/RELEASE.md +++ b/.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 +``` diff --git a/.github/workflows/deploy.yaml b/.github/workflows/docs-main.yaml similarity index 76% rename from .github/workflows/deploy.yaml rename to .github/workflows/docs-main.yaml index a2d8b5d4..8675f1b9 100644 --- a/.github/workflows/deploy.yaml +++ b/.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 diff --git a/.github/workflows/docs-release.yaml b/.github/workflows/docs-release.yaml new file mode 100644 index 00000000..25ceedc5 --- /dev/null +++ b/.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 diff --git a/.release-notes/_template.md b/.release-notes/_template.md index 7131ad5f..81ab067b 100644 --- a/.release-notes/_template.md +++ b/.release-notes/_template.md @@ -15,5 +15,7 @@ Release notes for `TODO`. ## :wrench: Fixes :wrench: +## :books: Docs :books: + ## :guitar: Misc :guitar: --> diff --git a/.release-notes/main.md b/.release-notes/main.md index 7131ad5f..702a8641 100644 --- a/.release-notes/main.md +++ b/.release-notes/main.md @@ -17,3 +17,7 @@ Release notes for `TODO`. ## :guitar: Misc :guitar: --> + +## :books: Docs :books: + +- Added multi version docs support diff --git a/Makefile b/Makefile index 4b93f7da..0efa784d 100644 --- a/Makefile +++ b/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 # ######## diff --git a/website/mkdocs.base.yaml b/website/mkdocs.base.yaml index 436591e6..8020a155 100644 --- a/website/mkdocs.base.yaml +++ b/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