docs.yml

name: Deploy Docs

on:
  push:
    branches: ["master", "main"]
    paths:
      - 'src/**'
      - 'coverage/**'
      - 'benchmark/**'
      - 'test/**'
      - 'docs/website-src/**'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: ["master", "main"]
    paths:
      - 'src/**'
      - 'coverage/**'
      - 'benchmark/**'
      - 'test/**'
      - 'docs/website-src/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: write   # publish generated dashboard data to the data branch
  pages: write
  id-token: write

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

jobs:
  api-coverage:
    name: NumPy API + Tests & Oracle inventories
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Setup .NET
        uses: actions/setup-dotnet@v6
        with:
          dotnet-version: |
            8.0.x
            10.0.x

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.12'

      - name: Install pinned NumPy reference
        run: python -m pip install numpy==2.4.2

      - name: Generate coverage artifact
        run: python coverage/generate_coverage.py --output artifacts/numpy-numsharp-coverage

      - name: Audit latest NumPy documentation links
        run: python coverage/audit_documentation.py artifacts/numpy-numsharp-coverage/coverage.json

      # master carries NO committed dashboard data any more (it lives only on the `data` branch),
      # so there is nothing to diff against — CI generates fresh here and publishes it below.
      - name: Generate Tests & Oracle inventory
        run: python test/inventory/generate_test_inventory.py --output artifacts/tests-oracle-inventory

      - name: Stage generated inventory locally (gitignored; audit_coverage reads coverage/generated)
        run: |
          mkdir -p coverage/generated
          cp -r artifacts/numpy-numsharp-coverage/. coverage/generated/

      - name: Generate benchmark API coverage ledger
        run: python benchmark/scripts/audit_coverage.py

      - name: Verify benchmark NumPy twin join keys
        run: |
          mkdir -p benchmark/results/smoke
          for suite in arithmetic unary reduction broadcast creation manipulation slicing comparison bitwise logic statistics sorting linalg selection fft random ndarray api; do
            python benchmark/NumSharp.Benchmark.Python/numpy_benchmark.py \
              --suite "$suite" --quick --size small \
              --output "benchmark/results/smoke/$suite.json" >/dev/null
          done
          python benchmark/scripts/check_smoke_joins.py

      - name: Execute every official C# benchmark body once
        # -p:ReferenceNDArrayAnalyzer=false: this file-based app forces net8.0 as a global onto the
        # whole graph, which would otherwise restore NumSharp.Core's netstandard2.0-only NDArray
        # analyzer for net8.0 (NETSDK1005). The smoke only runs benchmark bodies, so it drops the
        # analyzer via a command-line global (a #:property in the .cs does not propagate to the ref).
        run: dotnet run -c Release -f net8.0 --no-cache -p:ReferenceNDArrayAnalyzer=false benchmark/scripts/smoke_benchmark_bodies.cs

      # Publish the freshly generated data to the orphan `data` branch as a new <date>_<sha>
      # snapshot per type + a refreshed real `latest/` directory (publish.py). Only on master
      # pushes (never PRs), so PR builds cannot mutate the data branch. inventory + tests-oracle
      # + benchmark-coverage ride here; the heavy `benchmark` report is published by benchmark.yml
      # after a benchmark run. The `data` branch is the ONLY home of this data (master keeps none).
      - name: Publish dashboard data to the data branch
        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
        run: |
          set -euo pipefail
          git config user.name  "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git fetch origin data --depth=1
          git worktree add -B data /tmp/data origin/data
          python tools/dashboard_data/publish.py --type inventory \
            --from artifacts/numpy-numsharp-coverage --branch-worktree /tmp/data --sha "${GITHUB_SHA}" --commit
          python tools/dashboard_data/publish.py --type tests-oracle \
            --from artifacts/tests-oracle-inventory --branch-worktree /tmp/data --sha "${GITHUB_SHA}" --commit
          python tools/dashboard_data/publish.py --type benchmark-coverage \
            --from benchmark/coverage/generated --branch-worktree /tmp/data --sha "${GITHUB_SHA}" --commit
          git -C /tmp/data push origin data

      - name: Upload coverage artifact
        uses: actions/upload-artifact@v7
        if: always()
        with:
          name: numpy-numsharp-api-coverage
          path: artifacts/numpy-numsharp-coverage/
          if-no-files-found: error
          retention-days: 14

      - name: Upload Tests & Oracle inventory artifact
        uses: actions/upload-artifact@v7
        if: always()
        with:
          name: numsharp-tests-oracle-inventory
          path: artifacts/tests-oracle-inventory/
          if-no-files-found: error
          retention-days: 14

  build-and-deploy:
    needs: api-coverage
    if: github.event_name != 'pull_request'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0   # full history for DocFX per-page "last updated" git dates

      # All dashboard data comes from the `data` branch — checked out at its TIP by a direct shallow
      # clone into the refs/data submodule path. The gitlink is provenance only and is intentionally
      # never bumped, so `git submodule update --remote` cannot resolve it (and origin/data has already
      # advanced this run via the publish job above); a direct clone always floats to the newest
      # published snapshots. DocFX reads refs/data/<type>/latest directly (see docfx.json).
      - name: Fetch dashboard data (data branch, latest)
        run: |
          set -euo pipefail
          rm -rf refs/data
          git clone --depth 1 --single-branch --branch data \
            https://github.com/SciSharp/NumSharp.git refs/data

      - name: Render benchmark report pages from the data submodule
        run: |
          set -euo pipefail
          { printf '# Operation Matrix — NumSharp vs NumPy (full report)\n\n'
            printf '> _Auto-generated at docs-build from the `data` branch (refs/data/benchmark/latest) — do not edit by hand._\n\n'
            tail -n +2 refs/data/benchmark/latest/benchmark-report.md
          } > docs/website-src/docs/benchmark-matrix.md
          { printf '# Iterator Benchmark — NDIter vs NumPy (full sheet)\n\n'
            printf '> _Auto-generated at docs-build from the `data` branch (refs/data/benchmark/latest) — do not edit by hand._\n\n'
            cat refs/data/benchmark/latest/nditer_results.md
          } > docs/website-src/docs/benchmark-iterator.md

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.12'

      - name: Setup .NET
        uses: actions/setup-dotnet@v6
        with:
          dotnet-version: |
            8.0.x
            10.0.x

      - name: Install DocFX
        run: dotnet tool install -g docfx

      - name: Build docs
        run: docfx docs/website-src/docfx.json

      - name: Generate AI-friendly docs (llms.txt)
        run: |
          cd docs/website-src
          chmod +x scripts/generate-llms-txt.sh
          ./scripts/generate-llms-txt.sh ../website

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

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: 'docs/website'

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