docs.yml

# Checks and publishes the MkDocs Material site.
#
# Everything about rendering this site lives here, and nothing about it lives
# in scripts/test.sh. That split is the point: test.sh gates the product — the
# CLI, the MCP server, the bridge, the desktop app, the dataset and example
# regressions — and it runs on three operating systems because the product
# does. Rendering documentation is a GitHub Pages concern that runs in exactly
# one place on exactly one host, so keeping it in the product suite bought
# nothing and cost two Windows-only failures that had nothing to do with
# documentation.
#
# There is deliberately NO path filter. Generated pages are rendered from
# catalogs scattered across bxp-core, bxp-cli, bxp-mcp, bxp-gui-bridge and the
# Dart side, from `@typeInfo` over the live types, and from the header comment
# of every script — so "which paths can change the site" is very nearly "all of
# them", and every attempt to enumerate it would be one commit away from being
# wrong. Running on every push and pull request is cheaper than that mistake.
#
# The drift check regenerates every page and fragment and byte-diffs the result
# against what is committed, which is why this workflow needs Zig, Flutter and
# Python. A pull request runs the check and the build but never deploys.
#
# Zig is also needed for one artifact: the expression scratchpad's engine
# (docs/assets/wasm/bxp-eval.wasm, bxp-core compiled for wasm32-freestanding).
# It is a build output, deliberately untracked, so without this step the site
# deploys with every clickable expression reporting a failed engine load.
#
# `mkdocs build --strict` turns broken internal links and orphaned pages into
# build failures, so a bad link stops the deploy rather than shipping.
#
# One-time repo setting this depends on: Settings → Pages → Source must be
# "GitHub Actions". With the default "Deploy from a branch" the deploy step
# fails; there is no gh-pages branch and deliberately so.

name: docs

on:
  push:
    branches: [master]
  pull_request:
  # Manual runs for a first publish, or to redeploy without touching a page.
  workflow_dispatch:

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

# Matches ci.yml: every pinned action ships a Node 24 build except
# `mlugg/setup-zig`, which still declares `using: node20`. This flag keeps it
# off the deprecated runtime; drop it once setup-zig ships node24.
env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

# Serialise deploys, but never cancel one in flight — a half-finished Pages
# deployment is worse than a queued one.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-python@v7
        with:
          python-version: "3.13"
          cache: pip
          cache-dependency-path: scripts/docs/requirements.txt

      # The `social` plugin renders the Open Graph cards through Cairo, which
      # needs system libraries the Python wheels do not carry.
      - name: Install Cairo and font libraries
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev

      # Social cards are expensive to render and change only when a page title
      # or the theme palette does. Material keys its own cache by content, so a
      # stale restore is corrected, never served.
      - name: Restore the social-card cache
        uses: actions/cache@v6
        with:
          path: .cache
          key: mkdocs-material-${{ hashFiles('mkdocs.yml', 'scripts/docs/requirements.txt') }}-${{ github.sha }}
          restore-keys: |
            mkdocs-material-${{ hashFiles('mkdocs.yml', 'scripts/docs/requirements.txt') }}-
            mkdocs-material-

      - uses: mlugg/setup-zig@v2
        with:
          version: 0.16.0
          use-cache: false

      # Same rationale as ci.yml: mlugg's built-in cache keeps only a subset of
      # the build cache, so persist it here and let the toolchain download stay
      # cached on its own.
      - name: Cache Zig build artifacts
        uses: actions/cache@v6
        with:
          path: ${{ github.workspace }}/.zig-cache
          key: zig-docs-wasm-${{ hashFiles('bxp-core/**/*.zig', 'bxp-core/build.zig.zon') }}
          restore-keys: |
            zig-docs-wasm-

      # Flutter is here for one reason: three reference pages are rendered from
      # Dart catalogs (GuiToolDoc, the shortcut table, the prefs keys), and the
      # generator that reads them has to run as a `flutter test` because
      # importing bxp_gui links dart:ui. Trimmed to the desktop subset for the
      # same cache-budget reason as ci.yml.
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: 3.47.0
          channel: stable
          cache: true
          cache-key: "flutter-desktop-:os:-:channel:-:version:"
      - name: Trim Flutter SDK to the desktop subset
        run: |
          flutter config --no-enable-android --no-enable-ios
          eng="$FLUTTER_ROOT/bin/cache/artifacts/engine"
          if [ -n "$FLUTTER_ROOT" ] && [ -d "$eng" ]; then
            find "$eng" -maxdepth 1 -type d -name 'android-*' -exec rm -rf {} + 2>/dev/null || true
          fi

      # Regenerate every page and fragment and byte-diff against what is
      # committed. This is the gate that a catalog change cannot be pushed
      # without the page it feeds; it fails before anything is published.
      - name: Check generated pages against their sources
        run: bash scripts/docs/gen-docs.sh --check

      - name: Build the scratchpad engine
        run: bash scripts/docs/gen-wasm-playground.sh

      # The whole premise of the scratchpad is that the browser runs the SAME
      # evaluator as bxp-cli. Prove it before publishing: every expression in
      # the cross-runner corpus is evaluated through the wasm build and through
      # the native one, and the per-expression results must match byte for byte.
      - name: Check wasm/native parity
        run: bash scripts/docs/check-wasm-parity.sh

      - name: Install the docs toolchain
        run: pip install -r scripts/docs/requirements.txt

      - name: Build the site
        run: mkdocs build --strict

      # v4 stopped putting dotfiles in the artifact (v5 adds an
      # `include-hidden-files` opt-in). Checked before the bump: mkdocs
      # writes no dotfile into site/ — no .nojekyll either, and none is
      # needed, since a Pages artifact is served as-is and never sees
      # Jekyll — and docs/ carries no dotfile to copy.
      - uses: actions/upload-pages-artifact@v5
        with:
          path: site

  deploy:
    needs: build
    # Pull requests check and build the site; only master publishes it.
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5