docs.yml

# Build the docs on every push to `main` (then deploy to GitHub Pages)
# and on every pull request targeting `main` (build only, no deploy).
# The PR build catches broken mkdocstrings refs, missing images, and
# unresolved cross-links *before* they land on `main` and break the
# next deploy.
#
# Local equivalent: `scripts/build_docs.sh` (mkdocs build --strict).
# This workflow file is dormant until the repo is published with Pages
# enabled — keep it under version control so the deployment pipeline is
# reproducible from a clean checkout.

name: docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"
      - name: Install package + docs extras
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[docs]"
      - name: Generate chart assets
        # Renders docs/images/*.png and docs/charts/*.html from the
        # example modules. Both directories are gitignored — the docs
        # site references them, so they must exist before mkdocs runs.
        run: python scripts/generate_docs_assets.py
      - name: Build site
        run: mkdocs build --strict
      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./site

  deploy:
    # Only deploy on push-to-main. PRs (especially from forks) lack
    # `pages: write` permissions and would publish PR-only content to
    # the live site if they did. The build job above still runs on PRs
    # — that's where docs regressions get caught pre-merge.
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5