# Build TypeDoc HTML on every push to `main` and publish to GitHub Pages.
# Separate from ci.yml so that doc deploys never gate code merges — a failing
# Pages run is loud but does not block the verify pipeline. First-time setup:
# Repo Settings → Pages → Source → "GitHub Actions" (one click, then this
# workflow owns the rest).

name: Docs

on:
  push:
    branches: [main]
  workflow_dispatch: {}

# Only one Pages deploy at a time. Don't cancel in-flight: cancelling halfway
# through actions/deploy-pages can leave the Pages site in a half-published
# state. Queue instead.
concurrency:
  group: pages
  cancel-in-progress: false

# pages:write + id-token:write are the two permissions actions/deploy-pages
# requires (OIDC trust between the runner and Pages). contents:read for the
# checkout. Everything else stays at the org default of "none".
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    name: Build TypeDoc site
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node from .nvmrc
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build TypeDoc HTML
        run: npm run docs

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 5
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4