docs.yml

name: Documentation

on:
  push:
    branches: [main]
  pull_request:
  merge_group:
    types: [checks_requested]
  workflow_dispatch:

concurrency:
  group: docs-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  documentation:
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
        with:
          python-version: '3.11'
      - name: Install documentation and example dependencies
        run: |
          python -m pip install -r requirements-docs.txt pytest numpy
          python -m pip install 'torch>=2.2,<2.6' --index-url https://download.pytorch.org/whl/cpu
      - name: Build documentation with strict links and anchors
        run: |
          python tools/docs/check_punctuation.py
          python -m mkdocs build --strict
      - name: Build the documented engine interfaces
        run: |
          cmake -S . -B build-docs -DCMAKE_BUILD_TYPE=Release -DENGINE_NATIVE=OFF -DENGINE_VIZ=OFF
          cmake --build build-docs --target ChessEngine ChessEngine-validator -j2
      - name: Check examples and protocol reference
        env:
          ENGINE_BIN: ${{ github.workspace }}/build-docs/bin/ChessEngine
          VALIDATOR_BIN: ${{ github.workspace }}/build-docs/bin/ChessEngine-validator
        run: |
          python -m pytest tests/docs -v --junitxml=docs-results.xml
          python -c "import xml.etree.ElementTree as E; r=E.parse('docs-results.xml'); assert not r.findall('.//skipped'), 'Executable documentation tests were skipped'"
      - name: Run the tiny CPU training walkthrough
        env:
          OMP_NUM_THREADS: '2'
          MKL_NUM_THREADS: '2'
        run: |
          python tools/run_pipeline.py --input examples/training_positions.txt --workdir runs/docs-cpu --hidden 128 --epochs 1 --batch-size 4 --shard-size 4 --device cpu --engine build-docs/bin/ChessEngine --tolerance-cp 0 --output artifacts/docs-candidate.nnue
          python tools/nnue/check_vector64.py artifacts/docs-candidate.nnue