docs.yml

name: Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-docs:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.11"

    - name: Cache pip packages
      uses: actions/cache@v4
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-docs-${{ hashFiles('**/setup.py', '**/requirements*.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-docs-
          ${{ runner.os }}-pip-

    - name: Install system dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y libproj-dev proj-data proj-bin libgeos-dev
        sudo apt-get install -y pandoc

    - name: Install package with docs dependencies
      env:
        CUDA_VISIBLE_DEVICES: "-1"
      run: |
        python -m pip install --upgrade pip
        pip install wheel
        pip install -e ".[docs]"

    - name: Build documentation
      run: |
        cd docs
        make clean
        make html

    - name: Check for documentation warnings
      run: |
        cd docs
        # Build docs and capture output
        make html 2>&1 | tee build_output.txt

        # Check for warnings, excluding known harmless ones
        if grep -i "warning" build_output.txt | grep -v "Protobuf gencode version" | grep -v "UserWarning" | grep -v "warnings\.warn" | grep -q .; then
          echo "Documentation build produced warnings (excluding protobuf warnings):"
          grep -i "warning" build_output.txt | grep -v "Protobuf gencode version" | grep -v "UserWarning" | grep -v "warnings\.warn"
          exit 1
        fi

        echo "Documentation build completed successfully (protobuf warnings ignored)"

    - name: Upload documentation artifacts
      uses: actions/upload-artifact@v4
      with:
        name: documentation
        path: docs/build/html/