From 251a87e622c67ceeb1f425feaaf3ef02ff569efb Mon Sep 17 00:00:00 2001 From: polarathene <5098581+polarathene@users.noreply.github.com> Date: Thu, 11 Mar 2021 17:57:16 +1300 Subject: [PATCH] docs(ci): Add versioning support without using 'mike' It seems it may have be simpler to just use 'mike'.. Additionally squashes related commits providing minor fixes + improvements: - Use a job dependency (`needs`) to avoid `push` event race conditions due to parallel jobs. - Improve workflow file documentation via inline comments. - Make ShellCheck linting happy. - `chown` doesn't seem to work unless on the default branch for CI. Opted to use the docker `--user` approach instead. --- .github/workflows/deploy-docs.yml | 85 +++++++++++++++++-- .../scripts/docs/update-versions-json.sh | 59 +++++++++++++ docs/mkdocs.yml | 7 ++ 3 files changed, 144 insertions(+), 7 deletions(-) create mode 100755 .github/workflows/scripts/docs/update-versions-json.sh diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 8aeba50a..a721a8ed 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -8,11 +8,18 @@ on: paths: - '.github/workflows/deploy-docs.yml' - 'docs/**' + # Responds to tags being pushed (branches and paths conditions above do not apply to tags). + # Takes a snapshot of the docs from the tag (unaffected by branch or path restraints above), + # Stores build in a subdirectory with name matching the git tag `v.` substring: + tags: + - 'v[0-9]+.[0-9]+*' -# Jobs will run shell commands from this subdirectory: -defaults: - run: - working-directory: docs +env: + # Default docs version to build and deploy: + DOCS_VERSION: edge + # Assign commit authorship to official Github Actions bot when pushing to the `gh-pages` branch: + GIT_USER: 'github-actions[bot]' + GIT_EMAIL: '41898282+github-actions[bot]@users.noreply.github.com' jobs: deploy: @@ -21,13 +28,77 @@ jobs: steps: - uses: actions/checkout@v2 + - name: 'Check if deploy is for a `v.` tag version instead of `edge`' + if: startsWith(github.ref, 'refs/tags/') + working-directory: docs + run: | + DOCS_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}") + echo "DOCS_VERSION=${DOCS_VERSION}" >> "${GITHUB_ENV}" + + # Docs should build referencing the tagged version instead: + sed -i "s|^\(site_url:.*\)edge|\1${DOCS_VERSION}|" mkdocs.yml + - name: 'Build with mkdocs-material via Docker' - run: docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build --strict + working-directory: docs + # --user is required for build output file ownership to match the CI user instead of the containers internal user + run: docker run --rm --user "$(id -u):$(id -g)" -v "${PWD}:/docs" squidfunk/mkdocs-material build --strict + + - name: 'If a tagged version, fix canonical links and remove `404.html`' + if: startsWith(github.ref, 'refs/tags/') + working-directory: docs/site + run: | + # 404 is not useful due to how Github Pages implement custom 404 support: + # (Note the edge 404.html isn't useful either as it's not copied to the `gh-pages` branch root) + rm 404.html + + # Replace '${DOCS_VERSION}' (defaults to 'edge') in the 'canonical' link element of HTML files, + # with the tagged docs version: + find . -type f -name "*.html" -exec \ + sed -i "s|^\(.*.` substring from tag name' + id: add-version + continue-on-error: true + working-directory: gh-pages + run: '../.github/workflows/scripts/docs/update-versions-json.sh' + + # If an actual change was made to `versions.json`, commit and push it. + # Otherwise the step is skipped instead of reporting job failure. + - name: 'Push update for `versions.json`' + if: ${{ steps.add-version.outcome == 'success' }} + working-directory: gh-pages + run: | + git config user.name ${{ env.GIT_USER }} + git config user.email ${{ env.GIT_EMAIL }} + git add versions.json + git commit -m "chore: Add ${{ env.DOCS_VERSION }} to version selector list" + git push diff --git a/.github/workflows/scripts/docs/update-versions-json.sh b/.github/workflows/scripts/docs/update-versions-json.sh new file mode 100755 index 00000000..6c27dc85 --- /dev/null +++ b/.github/workflows/scripts/docs/update-versions-json.sh @@ -0,0 +1,59 @@ +#!/bin/bash + +# CI ENV `GITHUB_REF` from Github Actions CI provides the tag or branch that triggered the build +# See `github.ref`: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context +# https://docs.github.com/en/actions/reference/environment-variables +function _update-versions-json { + # Extract the version tag, truncate `` version and any suffix beyond it. + local MAJOR_MINOR + MAJOR_MINOR=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}") + # Github Actions CI method for exporting ENV vars to share across a jobs steps + # https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable + echo "DOCS_VERSION=${MAJOR_MINOR}" >> "${GITHUB_ENV}" + + if [[ -z "${MAJOR_MINOR}" ]] + then + echo "Could not extract valid \`v.\` substring, exiting.." + exit 1 + fi + + local VERSIONS_JSON='versions.json' + local IS_VALID + IS_VALID=$(jq '.' "${VERSIONS_JSON}") + + if [[ ! -f "${VERSIONS_JSON}" ]] || [[ -z "${IS_VALID}" ]] + then + echo "'${VERSIONS_JSON}' doesn't exist or is invalid. Creating.." + echo '[{"version": "edge", "title": "edge", "aliases": []}]' > "${VERSIONS_JSON}" + fi + + + # Only add this tag version the first time it's encountered: + local VERSION_EXISTS + VERSION_EXISTS=$(jq --arg version "${MAJOR_MINOR}" '[.[].version == $version] | any' "${VERSIONS_JSON}") + + if [[ "${VERSION_EXISTS}" == "true" ]] + then + echo "${MAJOR_MINOR} docs are already supported. Nothing to change, exiting.." + exit 1 + else + echo "Added support for ${MAJOR_MINOR} docs." + # Add any logic here if you want the version selector to have a different label (`title`) than the `version` URL/subdirectory. + local TITLE=${TITLE:-${MAJOR_MINOR}} + + # Assumes the first element is always the "latest" unreleased version (`edge` for us), and then newest version to oldest. + # `jq` takes the first array element of array as slice, concats with new element, then takes the slice of remaining original elements to concat. + # Thus assumes this script is always triggered by newer versions, no older major/minor releases as our build workflow isn't setup to support rebuilding older docs. + local UPDATED_JSON + UPDATED_JSON=$(jq --arg version "${MAJOR_MINOR}" --arg title "${TITLE}" \ + '.[:1] + [{version: $version, title: $title, aliases: []}] + .[1:]' \ + "${VERSIONS_JSON}" + ) + + # See `jq` FAQ advising this approach to update file: + # https://github.com/stedolan/jq/wiki/FAQ + echo "${UPDATED_JSON}" > tmp.json && mv tmp.json "${VERSIONS_JSON}" + fi +} + +_update-versions-json diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 8fd516b7..c5eb1b00 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -17,6 +17,13 @@ theme: - navigation.tabs - navigation.expand +# We do not use `mike`, but enabling this will enable the version selector UI. +# It references `versions.json` on `gh-pages` branch, +# however we have a basic setup that only matches `version` to a subdirectory. +extra: + version: + provider: mike + markdown_extensions: - toc: permalink: ⚓︎