From a2da895c9ae19b91550b92459a883096773c9af8 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Wed, 26 Aug 2026 15:15:44 +0200 Subject: [PATCH 01/11] Add mike for versioning docs --- CONTRIBUTING.md | 9 ++++++++- Makefile | 30 ++++++++++++++++++++++++++++-- docs/requirements.txt | 1 + mkdocs.yml | 4 ++++ 4 files changed, 41 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc565910..76487f5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,10 +26,17 @@ The public documentation site is built with MkDocs Material. * `make docs-build` -* Preview documentation locally: +* Preview documentation locally (with + [mike](https://github.com/jimporter/mike)): * `make docs-serve` (override port with `PORT=8008 make docs-serve`) +* Deploy a version of the documentation: + + * `VERSION=3.2 ALIASES=latest PUSH=1 make docs-deploy` + * `VERSION=3.1 GIT_REF=v3.1.0 make docs-deploy` + * `DEFAULT_VERSION=latest PUSH=1 make docs-set-default` + * Refresh bundled JSON-LD context files: * `make download-bundled-contexts` diff --git a/Makefile b/Makefile index 2904be4d..57a43425 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,16 @@ -.PHONY: install test docs-install docs-build docs-serve upgrade-submodules download-bundled-contexts +.PHONY: install test docs-install docs-build docs-serve docs-deploy docs-set-default upgrade-submodules download-bundled-contexts PORT ?= 8000 +VERSION ?= +GIT_REF ?= +ALIASES ?= +DEFAULT_VERSION ?= latest +PUSH ?= +DOCS_DEPLOY_BRANCH ?= gh-pages +DOCS_DEPLOY_REMOTE ?= origin +DOCS_RETRO_WORKTREE ?= .docs-retro-worktree +MIKE_FLAGS ?= +MIKE_PUSH = $(if $(PUSH),--push,) install: pip install -e . @@ -17,7 +27,23 @@ docs-build: mkdocs build --strict docs-serve: - mkdocs serve --dev-addr 127.0.0.1:$(PORT) + mike serve --dev-addr 127.0.0.1:$(PORT) --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_FLAGS) + +docs-deploy: + @test -n "$(VERSION)" || (echo "VERSION is required, e.g. VERSION=3.2 make docs-deploy"; exit 1) + @if [ -n "$(GIT_REF)" ]; then \ + test ! -e "$(DOCS_RETRO_WORKTREE)" || (echo "$(DOCS_RETRO_WORKTREE) already exists"; exit 1); \ + set -e; \ + trap 'git worktree remove "$(DOCS_RETRO_WORKTREE)"' EXIT; \ + git worktree add --detach "$(DOCS_RETRO_WORKTREE)" "$(GIT_REF)"; \ + python -m pip install -e "$(DOCS_RETRO_WORKTREE)"; \ + mike deploy --config-file "$(DOCS_RETRO_WORKTREE)/mkdocs.yml" --update-aliases --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ + else \ + mike deploy --update-aliases --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ + fi + +docs-set-default: + mike set-default --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(DEFAULT_VERSION) upgrade-submodules: git submodule update --remote --init --recursive diff --git a/docs/requirements.txt b/docs/requirements.txt index 949e1aca..f1b25e94 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,7 @@ -r ../requirements.txt typing_extensions mkdocs-material==9.7.6 +mike>=2.1 mkdocs-macros-plugin==1.5.0 mkdocs-awesome-pages-plugin==2.10.1 mkdocstrings[python]>=0.30 diff --git a/mkdocs.yml b/mkdocs.yml index 1c1c9f6c..589c2c78 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,10 @@ repo_name: digitalbazaar/pyld exclude_docs: | **/AGENTS.md +extra: + version: + provider: mike + extra_css: - stylesheets/extra.css From 306898653e3ec22368405045f45d2d5380ff0831 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Thu, 27 Aug 2026 12:09:46 +0200 Subject: [PATCH 02/11] Alter github pages to build docs with mike --- .github/workflows/docs.yaml | 45 +++++++++++++++++++++++++++++++------ CONTRIBUTING.md | 5 +++++ Makefile | 8 ++++++- 3 files changed, 50 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 72cc2ccf..71e09ab2 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -2,6 +2,10 @@ name: Documentation on: push: + branches: + - master + tags: + - 'v*' pull_request: branches: - '**' @@ -9,11 +13,16 @@ on: permissions: {} concurrency: + # Versioned docs update the same Git branch and Pages deployment, so publish + # jobs must run one at a time. Do not cancel queued release-tag deploys. group: pages cancel-in-progress: false jobs: build: + # Release tags are published by the deploy job. This job keeps PR and master + # docs checks fast without building the same tag twice. + if: ${{ !startsWith(github.ref, 'refs/tags/v') }} runs-on: ubuntu-latest timeout-minutes: 10 permissions: @@ -30,24 +39,46 @@ jobs: run: make docs-install - name: Build documentation run: make docs-build - - name: Upload Pages artifact - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1 - with: - path: site deploy: - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} - needs: build + # Only release tags publish docs. A master push validates docs but must not + # move the `latest` alias or default version. + if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }} runs-on: ubuntu-latest timeout-minutes: 10 permissions: + # `mike` stores the complete versioned site on `gh-pages`. + contents: write + # GitHub Pages still publishes from this workflow's uploaded artifact. pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 + with: + # `mike` needs the existing `gh-pages` branch history so each release + # adds one version without dropping older versions. + fetch-depth: 0 + - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0 + with: + python-version: '3.14' + cache: pip + - run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - run: make docs-install + - run: | + VERSION="${GITHUB_REF_NAME#v}" + # Build this tag into the version store, mark it as the only `latest`, + # then export the full versioned site for GitHub Actions Pages. + make docs-deploy VERSION="$VERSION" ALIASES=latest + make docs-set-default DEFAULT_VERSION=latest PUSH=1 + make docs-export + - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1 + with: + path: site-versioned - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76487f5e..30206bca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,11 @@ The public documentation site is built with MkDocs Material. * `VERSION=3.2 ALIASES=latest PUSH=1 make docs-deploy` * `VERSION=3.1 GIT_REF=v3.1.0 make docs-deploy` * `DEFAULT_VERSION=latest PUSH=1 make docs-set-default` + * `make docs-export` + +The GitHub Pages source is GitHub Actions. The `gh-pages` branch is still used +by `mike` to store all rendered documentation versions, then the workflow +exports that branch and deploys it with `actions/deploy-pages`. * Refresh bundled JSON-LD context files: diff --git a/Makefile b/Makefile index 57a43425..50cbeece 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: install test docs-install docs-build docs-serve docs-deploy docs-set-default upgrade-submodules download-bundled-contexts +.PHONY: install test docs-install docs-build docs-serve docs-deploy docs-export docs-set-default upgrade-submodules download-bundled-contexts PORT ?= 8000 VERSION ?= @@ -8,6 +8,7 @@ DEFAULT_VERSION ?= latest PUSH ?= DOCS_DEPLOY_BRANCH ?= gh-pages DOCS_DEPLOY_REMOTE ?= origin +DOCS_EXPORT_DIR ?= site-versioned DOCS_RETRO_WORKTREE ?= .docs-retro-worktree MIKE_FLAGS ?= MIKE_PUSH = $(if $(PUSH),--push,) @@ -42,6 +43,11 @@ docs-deploy: mike deploy --update-aliases --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ fi +docs-export: + @test ! -e "$(DOCS_EXPORT_DIR)" || (echo "$(DOCS_EXPORT_DIR) already exists"; exit 1) + mkdir "$(DOCS_EXPORT_DIR)" + git archive "$(DOCS_DEPLOY_BRANCH)" | tar -x -C "$(DOCS_EXPORT_DIR)" + docs-set-default: mike set-default --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(DEFAULT_VERSION) From fbc3f5dfe10d2969a1252e56f70cc51f2155a93d Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Thu, 27 Aug 2026 13:06:51 +0200 Subject: [PATCH 03/11] Fix security issues --- .github/workflows/docs.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 71e09ab2..4c985ec7 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -61,10 +61,10 @@ jobs: # `mike` needs the existing `gh-pages` branch history so each release # adds one version without dropping older versions. fetch-depth: 0 + persist-credentials: false - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0 with: python-version: '3.14' - cache: pip - run: | git config user.name github-actions[bot] git config user.email 41898282+github-actions[bot]@users.noreply.github.com @@ -76,6 +76,11 @@ jobs: make docs-deploy VERSION="$VERSION" ALIASES=latest make docs-set-default DEFAULT_VERSION=latest PUSH=1 make docs-export + env: + # Let `mike` push through git without writing the token into .git/config. + GIT_CONFIG_COUNT: 1 + GIT_CONFIG_KEY_0: http.https://github.com/.extraheader + GIT_CONFIG_VALUE_0: "AUTHORIZATION: bearer ${{ github.token }}" - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1 with: path: site-versioned From df1beb1c2ecc180179862383910587f5ec357f99 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Thu, 27 Aug 2026 14:20:00 +0200 Subject: [PATCH 04/11] Also build versioned docs on PR/master --- .github/workflows/docs.yaml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 4c985ec7..b1325d74 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,8 +37,18 @@ jobs: cache: 'pip' - name: Install documentation dependencies run: make docs-install - - name: Build documentation - run: make docs-build + - name: Build versioned documentation + run: | + # Exercise the same `mike deploy` and export path used by releases, + # but on a local throwaway branch with no push, alias, or default. + VERSION=pr-preview \ + DOCS_DEPLOY_BRANCH=docs-preview \ + MIKE_FLAGS="--ignore-remote-status" \ + make docs-deploy + + DOCS_DEPLOY_BRANCH=docs-preview \ + DOCS_EXPORT_DIR=site-versioned \ + make docs-export deploy: # Only release tags publish docs. A master push validates docs but must not From 511a4348f6415e0d43a61efba9bf29849f4a0136 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Thu, 27 Aug 2026 14:26:31 +0200 Subject: [PATCH 05/11] Fix credentials and make flow nicer --- .github/workflows/docs.yaml | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index b1325d74..9cf5b6cf 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,6 +37,10 @@ jobs: cache: 'pip' - name: Install documentation dependencies run: make docs-install + - name: Configure git identity + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com - name: Build versioned documentation run: | # Exercise the same `mike deploy` and export path used by releases, @@ -75,11 +79,14 @@ jobs: - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0 with: python-version: '3.14' - - run: | + - name: Install documentation dependencies + run: make docs-install + - name: Configure git identity + run: | git config user.name github-actions[bot] git config user.email 41898282+github-actions[bot]@users.noreply.github.com - - run: make docs-install - - run: | + - name: Build and export documentation version + run: | VERSION="${GITHUB_REF_NAME#v}" # Build this tag into the version store, mark it as the only `latest`, # then export the full versioned site for GitHub Actions Pages. From a8a445e01a9e9883f783dac46bbca2f958f05b49 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Mon, 31 Aug 2026 11:17:40 +0200 Subject: [PATCH 06/11] Patch mkdocs.yml during deploy for older docs versions that predate Material's mike version selector config --- Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Makefile b/Makefile index 50cbeece..40d4c0ae 100644 --- a/Makefile +++ b/Makefile @@ -37,6 +37,8 @@ docs-deploy: set -e; \ trap 'git worktree remove "$(DOCS_RETRO_WORKTREE)"' EXIT; \ git worktree add --detach "$(DOCS_RETRO_WORKTREE)" "$(GIT_REF)"; \ + : "Older tags predate Material's mike version selector config, so patch mkdocs.yml."; \ + python -c 'from pathlib import Path; p = Path("$(DOCS_RETRO_WORKTREE)/mkdocs.yml"); s = p.read_text(); b = "extra:\n version:\n provider: mike\n\n"; p.write_text(s if "provider: mike" in s else s.replace("extra_css:", b + "extra_css:", 1) if "extra_css:" in s else s.rstrip() + "\n\n" + b)'; \ python -m pip install -e "$(DOCS_RETRO_WORKTREE)"; \ mike deploy --config-file "$(DOCS_RETRO_WORKTREE)/mkdocs.yml" --update-aliases --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ else \ From f52d54eae0587b2be84dd36ad8f1e2ce7c70f696 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Mon, 31 Aug 2026 11:32:33 +0200 Subject: [PATCH 07/11] Force delete docs retro worktree --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 40d4c0ae..ac5758a4 100644 --- a/Makefile +++ b/Makefile @@ -35,7 +35,7 @@ docs-deploy: @if [ -n "$(GIT_REF)" ]; then \ test ! -e "$(DOCS_RETRO_WORKTREE)" || (echo "$(DOCS_RETRO_WORKTREE) already exists"; exit 1); \ set -e; \ - trap 'git worktree remove "$(DOCS_RETRO_WORKTREE)"' EXIT; \ + trap 'git worktree remove --force "$(DOCS_RETRO_WORKTREE)"' EXIT; \ git worktree add --detach "$(DOCS_RETRO_WORKTREE)" "$(GIT_REF)"; \ : "Older tags predate Material's mike version selector config, so patch mkdocs.yml."; \ python -c 'from pathlib import Path; p = Path("$(DOCS_RETRO_WORKTREE)/mkdocs.yml"); s = p.read_text(); b = "extra:\n version:\n provider: mike\n\n"; p.write_text(s if "provider: mike" in s else s.replace("extra_css:", b + "extra_css:", 1) if "extra_css:" in s else s.rstrip() + "\n\n" + b)'; \ From 1f3aa0bd68c4c7614a72dccb937c438106c131d8 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Tue, 1 Sep 2026 09:26:11 +0200 Subject: [PATCH 08/11] Use copy instead of symlink for latest --- Makefile | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index ac5758a4..b736af6c 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,7 @@ VERSION ?= GIT_REF ?= ALIASES ?= DEFAULT_VERSION ?= latest +DOCS_ALIAS_TYPE ?= copy PUSH ?= DOCS_DEPLOY_BRANCH ?= gh-pages DOCS_DEPLOY_REMOTE ?= origin @@ -40,9 +41,9 @@ docs-deploy: : "Older tags predate Material's mike version selector config, so patch mkdocs.yml."; \ python -c 'from pathlib import Path; p = Path("$(DOCS_RETRO_WORKTREE)/mkdocs.yml"); s = p.read_text(); b = "extra:\n version:\n provider: mike\n\n"; p.write_text(s if "provider: mike" in s else s.replace("extra_css:", b + "extra_css:", 1) if "extra_css:" in s else s.rstrip() + "\n\n" + b)'; \ python -m pip install -e "$(DOCS_RETRO_WORKTREE)"; \ - mike deploy --config-file "$(DOCS_RETRO_WORKTREE)/mkdocs.yml" --update-aliases --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ + mike deploy --config-file "$(DOCS_RETRO_WORKTREE)/mkdocs.yml" --update-aliases --alias-type=$(DOCS_ALIAS_TYPE) --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ else \ - mike deploy --update-aliases --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ + mike deploy --update-aliases --alias-type=$(DOCS_ALIAS_TYPE) --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_PUSH) $(MIKE_FLAGS) $(VERSION) $(ALIASES); \ fi docs-export: From 1e78417662505cad063b2102562580a5426dc6a9 Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Tue, 1 Sep 2026 09:31:40 +0200 Subject: [PATCH 09/11] Revert back to mkdocs for local preview --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index b736af6c..d5d20257 100644 --- a/Makefile +++ b/Makefile @@ -29,8 +29,8 @@ docs-build: mkdocs build --strict docs-serve: - mike serve --dev-addr 127.0.0.1:$(PORT) --remote $(DOCS_DEPLOY_REMOTE) --branch $(DOCS_DEPLOY_BRANCH) $(MIKE_FLAGS) - + mkdocs serve --dev-addr 127.0.0.1:$(PORT) + docs-deploy: @test -n "$(VERSION)" || (echo "VERSION is required, e.g. VERSION=3.2 make docs-deploy"; exit 1) @if [ -n "$(GIT_REF)" ]; then \ From a16934349726d58e95f43d5ade0dfc10f5f9f07c Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Tue, 1 Sep 2026 09:38:11 +0200 Subject: [PATCH 10/11] Update CONTRIBUTING.md to mention deploying docs during release process. --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30206bca..3da328c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,10 +56,12 @@ exports that branch and deploys it with `actions/deploy-pages`. * commit changes * `$EDITOR lib/pyld/__about__.py`: update to release version and remove `-dev` suffix. * `git commit CHANGELOG.md lib/pyld/__about__.py -m "Release {version}."` -* `git tag {version}` +* `git tag v{version}`. Release tags must use the `v` prefix because the + documentation publish workflow only runs for `v*` tags. * `$EDITOR lib/pyld/__about__.py`: update to next version and add `-dev` suffix. * `git commit lib/pyld/__about__.py -m "Start {next-version}."` -* `git push --tags` +* `git push origin v{version}`. This deploys the versioned documentation site + and updates the `latest` docs alias. To ensure a clean [package](https://pypi.org/project/PyLD/) upload to [PyPI](https://pypi.org/), use a clean checkout, and run the following: @@ -72,7 +74,7 @@ use a clean checkout, and run the following: for use in the upload command. * The below builds and uploads a sdist and wheel. Adjust as needed depending on how you manage and clean "dist/" dir files. -* `git checkout {version}` +* `git checkout v{version}` * `python3 -m build` * `twine check dist/*` * `twine upload -r PyLD dist/*` From 545a50626e71abe74a5b6df3053ad4371fdbaa0e Mon Sep 17 00:00:00 2001 From: Miel Vander Sande Date: Tue, 1 Sep 2026 13:20:49 +0200 Subject: [PATCH 11/11] Also build a moving dev version of the master branch --- .github/workflows/docs.yaml | 28 +++++++++++++++++----------- CONTRIBUTING.md | 11 ++++++++--- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9cf5b6cf..9c257e9f 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -20,9 +20,9 @@ concurrency: jobs: build: - # Release tags are published by the deploy job. This job keeps PR and master - # docs checks fast without building the same tag twice. - if: ${{ !startsWith(github.ref, 'refs/tags/v') }} + # Pushes are published by the deploy job. This job keeps PR docs checks fast + # without building the same commit twice. + if: ${{ github.event_name == 'pull_request' }} runs-on: ubuntu-latest timeout-minutes: 10 permissions: @@ -55,9 +55,9 @@ jobs: make docs-export deploy: - # Only release tags publish docs. A master push validates docs but must not - # move the `latest` alias or default version. - if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }} + # Release tags publish stable docs. Master publishes the moving `dev` + # version without moving the `latest` alias or default version. + if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')) }} runs-on: ubuntu-latest timeout-minutes: 10 permissions: @@ -87,11 +87,17 @@ jobs: git config user.email 41898282+github-actions[bot]@users.noreply.github.com - name: Build and export documentation version run: | - VERSION="${GITHUB_REF_NAME#v}" - # Build this tag into the version store, mark it as the only `latest`, - # then export the full versioned site for GitHub Actions Pages. - make docs-deploy VERSION="$VERSION" ALIASES=latest - make docs-set-default DEFAULT_VERSION=latest PUSH=1 + if [ "$GITHUB_REF" = "refs/heads/master" ]; then + # Publish current master as moving development docs only. + make docs-deploy VERSION=dev PUSH=1 + else + VERSION="${GITHUB_REF_NAME#v}" + # Build this tag into the version store, mark it as the only `latest`, + # then export the full versioned site for GitHub Actions Pages. + make docs-deploy VERSION="$VERSION" ALIASES=latest + make docs-set-default DEFAULT_VERSION=latest PUSH=1 + fi + make docs-export env: # Let `mike` push through git without writing the token into .git/config. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3da328c3..22491f09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,12 +26,12 @@ The public documentation site is built with MkDocs Material. * `make docs-build` -* Preview documentation locally (with - [mike](https://github.com/jimporter/mike)): +* Preview documentation locally: * `make docs-serve` (override port with `PORT=8008 make docs-serve`) -* Deploy a version of the documentation: +* Deploy a version of the documentation (with + [mike](https://github.com/jimporter/mike)): * `VERSION=3.2 ALIASES=latest PUSH=1 make docs-deploy` * `VERSION=3.1 GIT_REF=v3.1.0 make docs-deploy` @@ -42,6 +42,11 @@ The GitHub Pages source is GitHub Actions. The `gh-pages` branch is still used by `mike` to store all rendered documentation versions, then the workflow exports that branch and deploys it with `actions/deploy-pages`. +Pushing to `master` publishes the current branch as the moving `dev` +documentation version. Pushing a `v*` release tag publishes that release +version, updates the `latest` docs alias, and keeps `latest` as the default +documentation version. + * Refresh bundled JSON-LD context files: * `make download-bundled-contexts`