docs.yml

name: Docs Publish

on:
  push:
    branches: [main]
    paths:
      - docs/**
      - src/**
      - packages/mvtb-data/**
      - pyproject.toml
      - .github/workflows/docs.yml
  pull_request:
    branches: [main]
    paths:
      - docs/**
      - src/**
      - packages/mvtb-data/**
      - pyproject.toml
      - .github/workflows/docs.yml
  workflow_dispatch:

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

# Only one deployment at a time; don't cancel an in-progress deploy
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"

      - name: Check notebook bootstrap cells and outputs are in sync
        run: |
          python docs/notebooks/sync_bootstrap.py --check
          python docs/notebooks/clear_outputs.py --check

      - name: Install system dependencies
        run: sudo apt-get install -y graphviz

      - name: Install Python dependencies
        run: |
          pip install --upgrade pip
          pip install -r docs/requirements.txt
          cd packages/mvtb-data && pip install .

      - name: Build docs
        run: sphinx-build -b html docs/source docs/build/html

      - name: Build wheel for JupyterLite
        run: |
          pip install build
          python -m build --wheel --outdir docs/lite/pypi

      - uses: actions/setup-node@v7
        with:
          node-version: "22"
          cache: npm
          cache-dependency-path: docs/lite/wasm_check/package-lock.json

      - name: Check the JupyterLite install path actually works (real Pyodide, real WASM)
        run: |
          npm --prefix docs/lite/wasm_check ci
          node docs/lite/wasm_check/check_pyodide_install.mjs docs/lite/pypi/*.whl

      - name: Sync notebooks into JupyterLite content
        run: |
          mkdir -p docs/lite/files
          find docs/notebooks \
            -type f \
            -name '*.ipynb' \
            ! -path '*/.ipynb_checkpoints/*' \
            ! -path '*/old/*' \
            -print0 | while IFS= read -r -d '' nb; do
              rel="${nb#docs/notebooks/}"
              mkdir -p "docs/lite/files/$(dirname "$rel")"
                cp -p "$nb" "docs/lite/files/$rel"
            done

      - name: Adapt staged notebooks for JupyterLite
        run: |
          python - <<'PY'
          import json
          from pathlib import Path

          root = Path("docs/lite/files")
          for nb_path in root.rglob("*.ipynb"):
              with nb_path.open("r", encoding="utf-8") as f:
                  nb = json.load(f)

              meta = nb.setdefault("metadata", {})
              meta["kernelspec"] = {
                  "name": "python",
                  "display_name": "Python (Pyodide)",
                  "language": "python",
              }
              meta.setdefault("language_info", {})
              meta["language_info"]["name"] = "python"

              for cell in nb.get("cells", []):
                  if cell.get("cell_type") != "code":
                      continue
                  source = cell.get("source", [])
                  if isinstance(source, str):
                      lines = source.splitlines(keepends=True)
                  else:
                      lines = source

                  new_lines = []
                  changed = False
                  for line in lines:
                      if line.strip() in ("%matplotlib ipympl", "%matplotlib widget"):
                          newline = "\n" if line.endswith("\n") else ""
                          new_lines.append(f"%matplotlib inline{newline}")
                          changed = True
                      else:
                          new_lines.append(line)

                  if changed:
                      cell["source"] = (
                          new_lines
                          if not isinstance(source, str)
                          else "".join(new_lines)
                      )

              with nb_path.open("w", encoding="utf-8") as f:
                  json.dump(nb, f, indent=1)
                  f.write("\n")
          PY

      - name: Build JupyterLite site
        # jupyterlite-pyodide-kernel is pinned deliberately -- NOT for wasm-ABI
        # matching (MVTB is pure Python, unlike RTB's compiled-extension pin of
        # the same version, for a different reason). Newer kernel releases bundle
        # Pyodide >=0.27.7, which turned WebAssembly JSPI ("stack switching") on
        # by default for run_until_complete(). Browsers without JSPI support
        # (Safari has none as of 2026-08; Firefox only behind a flag) either
        # crash the kernel outright or, with the enableRunUntilComplete: false
        # workaround, turn run_until_complete into a fire-and-forget no-op --
        # letting a cell's package/import machinery run before an install has
        # actually finished landing (confirmed live on bdsim: intermittent
        # ModuleNotFoundError despite a successful-looking install cell).
        # jupyterlite-pyodide-kernel==0.6.1 bundles Pyodide 0.27.6, genuinely
        # predating this whole mechanism -- matches RTB's and bdsim's existing
        # pins. Installing jupyterlite-core directly rather than the jupyterlite
        # metapackage: the metapackage requires jupyterlite-core>=0.8.1, which
        # conflicts with this pin's jupyterlite-core<0.7.0 requirement.
        # Once Safari (and Firefox out-of-flag) ship JSPI, revisit this pin --
        # and docs/lite/wasm_check/package.json's matching pyodide npm pin.
        run: |
          pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server
          cd docs/lite && jupyter lite build --output-dir ../build/html/lite

      # Real browsers, pre-deploy: gates publishing, so skipped for pull_request
      # (which only builds).  The Node/Pyodide check above covers dependency
      # drift; this covers JupyterLab itself starting (before any kernel exists)
      # and the kernel running the bootstrap cell, in Chromium and WebKit.
      - name: Install browsers for the JupyterLite browser check
        if: github.event_name != 'pull_request'
        run: |
          pip install playwright
          playwright install --with-deps chromium webkit

      - name: Check the built JupyterLite site starts in a real browser
        if: github.event_name != 'pull_request'
        # Informational until it has run green once on main (it is skipped for
        # pull requests, so its first real CI run is on a publish).  Then delete
        # this line so a failure blocks the deploy.
        continue-on-error: true
        run: |
          python -m http.server 8000 --directory docs/build/html &
          sleep 3
          python docs/lite/browser_check/check_lite_in_browser.py \
            --base-url http://localhost:8000/lite \
            --retries 1 --screenshot-dir browser-check-screenshots

      - name: Upload browser-check screenshots
        if: failure() && github.event_name != 'pull_request'
        uses: actions/upload-artifact@v7
        with:
          name: lite-browser-check-screenshots
          path: browser-check-screenshots
          if-no-files-found: ignore

      - name: Package notebooks zip
        run: |
          rm -f docs/build/html/mvtb_notebooks.zip
          zip -r docs/build/html/mvtb_notebooks.zip docs/notebooks

      - name: Upload notebooks zip artifact
        uses: actions/upload-artifact@v7
        with:
          name: mvtb_notebooks
          path: docs/build/html/mvtb_notebooks.zip
          if-no-files-found: error

      # push and workflow_dispatch both publish; pull_request only builds
      # (to catch breakage in review), it never gets an artifact to deploy.
      - uses: actions/upload-pages-artifact@v5
        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
        with:
          path: docs/build/html

  deploy:
    needs: build
    runs-on: ubuntu-latest
    # ref check (not just event_name) so a manual dispatch from a
    # non-main branch builds but doesn't publish -- push is already
    # restricted to main via the `branches: [main]` filter above, but
    # workflow_dispatch can be run against any branch.
    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5