docs.yml

name: Docs (manual)
run-name: Docs deploy (manual) by ${{ github.actor }}

# Manual escape hatch for deploying docs between releases (the automatic publish lives in the Release
# workflow). Redeploys the docs of the LATEST released version (its MAJOR.MINOR mike version) from the
# selected ref's docs sources. Requires Pages source = "Deploy from a branch" (`gh-pages`, root).
on:
  workflow_dispatch:

# Layer CI-only overrides on top of pants.toml for the Pants build steps (see pants.ci.toml).
env:
  PANTS_CONFIG_FILES: pants.ci.toml

# Least-privilege default; the deploy job grants itself the gh-pages-push scope it needs.
permissions:
  contents: read

# Serialize with the release workflow's `gh-pages` deploy; let an in-progress deploy finish rather than
# cancelling it.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  deploy:
    name: Deploy versioned docs to gh-pages
    runs-on: ubuntu-latest
    permissions:
      contents: write # mike commits + pushes the version subdirectory to `gh-pages`
      pages: read # the smoke test polls the Pages build status of the pushed commit
    # The push only happens after this environment's approval gate.
    environment: github-pages
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          # Full history so mike can see/update the `gh-pages` branch and the latest release tag is visible.
          fetch-depth: 0
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.14"
      - name: Set up uv
        # The `[python] resolver = "uv"` resolve is built with uv, so Pants needs it on PATH.
        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
      - name: Initialize Pants
        uses: pantsbuild/actions/init-pants@v11
        with:
          gha-cache-key: docs-v0
          named-caches-hash: ${{ hashFiles('3rdparty/tools/tools-lockfile.json') }}
      # The `test` guards the site entry point: a missing docs/index.md still builds --strict-clean but
      # 404s `/` and `/latest/` once deployed.
      - name: Build docs site (validation)
        run: |
          pants run docs:mkdocs-pex -- build --strict
          test -f site/index.html
      # A between-release docs fix re-deploys the newest released MAJOR.MINOR (still aliased `latest`).
      - name: Deploy latest version's docs to gh-pages with mike
        run: |
          version="$(git describe --tags --abbrev=0 --match 'v[0-9]*')"
          docs_version="$(echo "${version#v}" | cut -d. -f1-2)"
          echo "docs_version=${docs_version}" >> "$GITHUB_ENV"
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          pants run docs:mike-pex -- deploy --push --update-aliases "${docs_version}" latest
          pants run docs:mike-pex -- set-default --push latest
      - name: Smoke test the published docs
        env:
          GH_TOKEN: ${{ github.token }}
        run: ./build_scripts/docs-smoke-test.sh "$(git rev-parse gh-pages)" "${docs_version}"