test-docs-examples.yml

name: Documentation Tests & Build

on:
  push:
    branches: [ main, master, development, dev ]
    paths:
      - 'docs/**'
  pull_request:
    branches: [ main, master, development, dev ]
    paths:
      - 'docs/**'
  workflow_dispatch:

env:
  RUSTFLAGS: -C debuginfo=0
  RUST_BACKTRACE: 1
  PYTHONUTF8: 1
  LLVM_VERSION: "14.0.6"

jobs:
  docs-ci:
    name: Test and build documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.10'

      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Set up Rust
        run: rustup show

      - name: Install just
        uses: extractions/setup-just@v3

      - name: Cache Rust
        uses: Swatinem/rust-cache@v2
        with:
          workspaces: |
            python/pecos-rslib
            python/pecos-rslib-llvm

      - name: Cache LLVM ${{ env.LLVM_VERSION }}
        id: cache-llvm
        uses: actions/cache@v4
        with:
          path: ~/.pecos/deps/llvm
          key: llvm-${{ env.LLVM_VERSION }}-${{ runner.os }}-${{ runner.arch }}

      - name: Install LLVM ${{ env.LLVM_VERSION }}
        if: steps.cache-llvm.outputs.cache-hit != 'true'
        run: cargo run -p pecos --features cli --release -- install llvm

      - name: Configure LLVM
        run: |
          PECOS_LLVM=$(cargo run -p pecos --features cli --release -- llvm find 2>/dev/null)
          echo "PECOS_LLVM=$PECOS_LLVM" >> $GITHUB_ENV
          echo "LLVM_SYS_140_PREFIX=$PECOS_LLVM" >> $GITHUB_ENV

      - name: Install dependencies and build
        run: |
          uv lock --project .
          uv sync --project . --all-packages
          cargo install --path crates/pecos --features cli
          pecos python build --profile debug

      - name: Test working documentation examples
        run: uv run python scripts/docs/test_working_examples.py

      - name: Build documentation
        if: success()
        run: uv run mkdocs build