quiver-dsp 0.3.3

name: Documentation

on:
  push:
    branches: [main, master]
    paths:
      - 'docs/**'
      - 'src/**'
      - 'Cargo.toml'
      - 'demos/browser/**'
      - 'packages/@quiver-dsp/**'
      - '.github/workflows/docs.yml'
  pull_request:
    paths:
      - 'docs/**'
      - 'src/**'
      - 'demos/browser/**'
      - 'packages/@quiver-dsp/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

# Cancel outdated runs for the same branch/PR
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  CARGO_TERM_COLOR: always

jobs:
  # Build both doc types in parallel
  build:
    name: Build Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      # Setup Rust for rustdoc + the wasm playground build
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown
      - uses: Swatinem/rust-cache@v2

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install wasm-pack
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

      # Install mdBook tools (taiki-e ships prebuilt binaries; peaceiris/actions-mdbook
      # is stuck on the deprecated node20 runtime)
      - name: Install mdBook
        uses: taiki-e/install-action@mdbook

      - name: Cache mdbook-mermaid
        id: cache-mermaid
        uses: actions/cache@v6
        with:
          path: ~/.cargo/bin/mdbook-mermaid
          key: mdbook-mermaid-${{ runner.os }}

      - name: Install mdbook-mermaid
        if: steps.cache-mermaid.outputs.cache-hit != 'true'
        run: cargo install mdbook-mermaid

      - name: Setup mdbook-mermaid
        run: mdbook-mermaid install docs/

      # Build both doc types in parallel
      - name: Build documentation
        run: |
          # Build mdBook and rustdoc in parallel. A bare `wait` returns 0
          # regardless of child exit status, so capture each PID and wait on it
          # individually; under `set -e` a nonzero child then fails the step.
          mdbook build docs/ &
          mdbook_pid=$!
          cargo doc --no-deps --all-features &
          cargo_doc_pid=$!
          wait "$mdbook_pid"
          wait "$cargo_doc_pid"
        env:
          # Match ci.yml's doc job. Do NOT set `--cfg docsrs` here: on the stable
          # toolchain that enables the nightly-only `feature(doc_cfg)` and fails
          # with E0554. docs.rs sets docsrs itself on nightly via
          # [package.metadata.docs.rs] in Cargo.toml.
          RUSTDOCFLAGS: -D warnings

      # Build the WASM playground (the browser synth demo running the real engine)
      - name: Build playground
        run: |
          npm ci
          make wasm
          npm run build:wasm:ts
          npm run build --workspace @quiver-dsp/demo-browser-synth

      # Combine into single site structure
      - name: Prepare site
        run: |
          mkdir -p site
          cp -r docs/book/* site/
          cp -r target/doc site/api
          cp -r demos/browser/dist site/playground

      - name: Upload site artifact
        uses: actions/upload-artifact@v7
        with:
          name: site
          path: site/

  # Validate documentation quality
  validate:
    name: Validate Documentation
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Download site
        uses: actions/download-artifact@v8
        with:
          name: site
          path: site/

      - name: Validate documentation structure
        run: |
          echo "Checking documentation structure..."

          # Check mdBook files
          html_count=$(find site -name "*.html" -not -path "site/api/*" | wc -l)
          echo "mdBook: $html_count HTML files"
          if [ "$html_count" -lt 20 ]; then
            echo "Error: Expected at least 20 mdBook HTML files, found $html_count"
            exit 1
          fi

          # Check rustdoc files
          api_count=$(find site/api -name "*.html" 2>/dev/null | wc -l)
          echo "Rustdoc: $api_count HTML files"
          if [ "$api_count" -lt 10 ]; then
            echo "Error: Expected at least 10 rustdoc HTML files, found $api_count"
            exit 1
          fi

          # Check for index files
          [ -f "site/index.html" ] || { echo "Missing site/index.html"; exit 1; }
          [ -f "site/api/quiver/index.html" ] || { echo "Missing API index"; exit 1; }

          # Check the WASM playground shipped with its engine binary
          [ -f "site/playground/index.html" ] || { echo "Missing playground index"; exit 1; }
          ls site/playground/assets/*.wasm >/dev/null 2>&1 || { echo "Missing playground wasm binary"; exit 1; }

          echo "Documentation validation passed!"

  # Deploy to GitHub Pages (main branch only)
  deploy:
    name: Deploy to GitHub Pages
    needs: [build, validate]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Download site
        uses: actions/download-artifact@v8
        with:
          name: site
          path: site/

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Upload to Pages
        uses: actions/upload-pages-artifact@v5
        with:
          path: site/

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