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/actions-gh-pages@v3.9.3
        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