breaking: Refactor getmail support (#4156)
#279
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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<MAJOR>.<MINOR>` 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<major>.<minor>` 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|^\(.*<link rel=\"canonical\".*\)${DOCS_VERSION}|\1latest|" \ | |
| {} | |
| - name: 'Deploy to Github Pages' | |
| uses: peaceiris/[email protected] | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| # Build directory contents to publish to the `gh-pages` branch: | |
| publish_dir: ./docs/site | |
| # Directory to place `publish_dir` contents on the `gh-pages` branch: | |
| destination_dir: ${{ env.DOCS_VERSION }} | |
| user_name: ${{ env.GIT_USER }} | |
| user_email: ${{ env.GIT_EMAIL }} | |
| add-version-to-docs: | |
| permissions: | |
| contents: write | |
| name: 'Update `versions.json` if necessary' | |
| runs-on: ubuntu-22.04 | |
| if: startsWith(github.ref, 'refs/tags/') | |
| # Avoid race condition with pushing to `gh-pages` branch by waiting for `deploy` to complete first | |
| needs: deploy | |
| steps: | |
| - name: 'Checkout the tagged commit (shallow clone)' | |
| uses: actions/checkout@v4 | |
| - name: 'Checkout the docs deployment branch to a subdirectory' | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages | |
| path: gh-pages | |
| # Updates `env.DOCS_VERSION` to the tag version; if invalid exits job early. | |
| - name: 'Ensure `versions.json` has `v<major>.<minor>` 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 |