docs.yml

name: Docs

# Build the combined documentation site — mdBook narrative + rustdoc API — and
# deploy it to GitHub Pages. It runs on the default branch (main) and on the
# staging/rewrite-in-rust-lol integration branch, so the published docs track the
# Rust rewrite as it lands on staging instead of waiting for the merge to main.
# The rustdoc output is nested under the book at /api, so a single artifact serves
# both the prose (at /) and the API reference (at /api). scripts/check-docs.sh
# runs the same build + assemble locally.
#
# The github-pages environment's deployment-branch-policy must also list any
# branch named here, or the deploy job is blocked at the environment gate.
on:
  push:
    branches: [main, staging/rewrite-in-rust-lol]
  workflow_dispatch:

# Least privilege at the workflow level: only checkout is needed by default. The
# Pages OIDC grants (pages:write + id-token:write) belong solely to the deploy
# job, so they are scoped there rather than handed to the build job too.
permissions:
  contents: read

# One Pages deploy at a time, and never cancel an in-flight deploy — a cancelled
# deploy can leave the live site half-published.
concurrency:
  group: pages
  cancel-in-progress: false

env:
  CARGO_TERM_COLOR: always
  # Any rustdoc warning (broken intra-doc link, undocumented item) fails the
  # build, so the published API reference cannot silently rot (AC2).
  RUSTDOCFLAGS: -D warnings

jobs:
  build:
    name: build site (mdBook + rustdoc)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # rust-toolchain.toml is the single source of truth for the toolchain
      # (channel + components); rustup installs it on first cargo use. See ci.yml.
      - name: Install pinned toolchain
        run: rustup show active-toolchain || rustup toolchain install

      - uses: Swatinem/rust-cache@v2

      - uses: taiki-e/install-action@v2
        with:
          tool: mdbook

      # API reference → target/doc. --no-deps keeps it to this workspace's crates;
      # RUSTDOCFLAGS (above) makes any warning fatal.
      - name: Build API docs (rustdoc)
        run: cargo doc --no-deps

      # Narrative site → docs/book/book, with client-side search (book.toml).
      - name: Build narrative docs (mdBook)
        run: mdbook build docs/book

      # Merge: nest the rustdoc tree under the book output at /api so one artifact
      # serves the book at / and the API reference at /api. Mirrors check-docs.sh.
      - name: Assemble merged site
        run: |
          rm -rf docs/book/book/api
          cp -R target/doc docs/book/book/api

      # AC-6 (#76) — build example course sites (webr + pyodide) into the Pages
      # artifact so the deployed docs include live, runnable example lessons.
      # Each site nests under /examples/{r,python}/, mirroring the /api nesting.
      - name: Build R example site (webR)
        run: cargo run --release -p blendtutor-cli -- build examples/write-less-code-r --target webr -o docs/book/book/examples/r

      - name: Build Python example site (Pyodide)
        run: cargo run --release -p blendtutor-cli -- build examples/write-less-code-python --target pyodide -o docs/book/book/examples/python

      # AC-2 (#152, updated by #227) — deploy demo-book into the Pages
      # artifact at /demo-book/, mirroring the /api + /examples nesting.
      # Quarto is not installed on this runner until setup@v2 runs, and the
      # demo-book renders into demo-book/_output/ (demo-book/_quarto.yml pins
      # output-dir: _output), so the copy must DOT-COPY (trailing /.): a bare
      # cp -R demo-book/_output dst would add a demo-book/_output/ layer and
      # /demo-book/ would 404. (The standalone demo — render, COI-scope
      # post-process, /demo/ assemble — was removed by #227.)
      - uses: quarto-dev/quarto-actions/setup@v2

      - name: Render demo-book (Quarto)
        run: quarto render demo-book --to html

      - name: Assemble demo-book into artifact (/demo-book/)
        run: |
          mkdir -p docs/book/book/demo-book
          cp -R demo-book/_output/. docs/book/book/demo-book/

      # AC-6 (#199) — assemble committed docs/evals/ into the Pages artifact at
      # /evals/, mirroring the /api + /examples/{r,python} + /demo-book/
      # nesting. Guarded: before AC-5 (#198) lands there is no
      # docs/evals/, and the if/then/fi guard keeps the job green (Actions runs
      # steps under `bash -eo pipefail` — an `&&` shorthand would exit 1 on a
      # missing dir). mkdir INSIDE the guard: no empty /evals/ nest published
      # pre-AC-5. rm before mkdir (api precedent docs.yml:67): docs/evals is
      # committed source; lesson deletion is a committed deletion; cp-only never
      # removes stale reports. DOT-COPY (trailing /.): a bare cp -R docs/evals
      # would double-nest to /evals/evals/<lesson>/ → 404.
      # AC-215 (#215) — docs.yml never runs check-docs.sh, so this step must
      # enforce the /Users/ leak pin itself: a polluted eval.json (dev-machine
      # absolute paths) would otherwise commit, CI stays green, and the /Users/
      # paths get served publicly at /evals/.
      - name: Assemble evals into artifact (/evals/)
        run: |
          if [ -d docs/evals ]; then
            if rg -l '/Users/' docs/evals/ | grep -q .; then
              echo "docs.yml: /Users/ leak in docs/evals/ (scrub per whole-game.md Eval report)" >&2
              exit 1
            fi
            rm -rf docs/book/book/evals
            mkdir -p docs/book/book/evals
            cp -R docs/evals/. docs/book/book/evals/
          fi

      - name: Add .nojekyll at artifact root
        run: touch docs/book/book/.nojekyll

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

  deploy:
    name: deploy to Pages
    needs: build
    runs-on: ubuntu-latest
    # Job-level permissions replace the workflow defaults: the Pages deploy needs
    # the OIDC token write + pages write, and nothing else (it consumes the
    # artifact the build job uploaded; it does not check out the repo).
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5