name: 'Documentation' on: workflow_dispatch: push: branches: - master 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]+*' 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: permissions: contents: write name: 'Deploy Docs' runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 - 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' working-directory: docs run: '../.github/workflows/scripts/docs/build-docs.sh' - 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 the tagged '${DOCS_VERSION}' in the 'canonical' link element of HTML files, # to point to the 'edge' version of docs as the authoritative source: 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 update-latest-symlink: permissions: contents: write name: 'update `latest` symlink if neccessary' runs-on: ubuntu-22.04 if: startsWith(github.ref, 'refs/tags/') needs: add-version-to-docs steps: - name: 'Checkout the docs deployment branch' uses: actions/checkout@v4 with: ref: gh-pages - name: 'Ensure `latest` symlink refers to the substring from tag name' id: update-latest run: | DOCS_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}") echo "DOCS_VERSION=${DOCS_VERSION}" >>"${GITHUB_ENV}" rm latest ln -s "${DOCS_VERSION}" latest - name: 'Push update for `latest` symlink' run: | git config user.name ${{ env.GIT_USER }} git config user.email ${{ env.GIT_EMAIL }} git add latest git commit -m "chore: Update \`latest\` symlink to point to ${{ env.DOCS_VERSION }}" git push