build-guidelines.yml

name: Build 
on:
  push:
    tags:
      - "*.*.*"
    branches:
      - "main"
  # this fires for the temporary branch the merge queue creates
  merge_group:
  pull_request:
    branches:
      - "main"
  # workflow_call trigger to make this workflow reusable
  workflow_call:
    # You can add inputs here if needed in the future
    # inputs:
    #   example_input:
    #     required: false
    #     type: string
    #     default: 'default value'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Install uv
        uses: astral-sh/setup-uv@v6
      - name: Build documentation
        run: |
          mkdir -p build
          ./make.py 2>&1 | tee build/build.log
          # Check for a wide range of error indicators in the log
          if grep -q -E "Traceback" build/build.log; then
            echo "::error::Build errors detected in log"
            
            # Extract error contexts and annotate them in the GitHub Actions UI
            echo "=== ERROR DETAILS ==="
            
            # Check for the Sphinx temp error file reference and extract it if present
            TEMP_ERROR_FILE=$(grep -o '/tmp/sphinx-err-[^ ]*\.log' build/build.log | head -1)
            if [ ! -z "$TEMP_ERROR_FILE" ] && [ -f "$TEMP_ERROR_FILE" ]; then
              # Save this traceback for artifacts
              echo "=== TRACEBACK ==="
              echo "Saving traceback to build/sphinx_traceback.log"
              cp "$TEMP_ERROR_FILE" build/sphinx_traceback.log
            fi
            
            # Check for FLS differences file reference and extract it if present
            FLS_DIFF_FILE=$(grep -o '/tmp/fls_diff_[^ ]*\.txt' build/build.log | head -1)
            if [ ! -z "$FLS_DIFF_FILE" ] && [ -f "$FLS_DIFF_FILE" ]; then
              # Save this differences file for artifacts
              echo "=== SPEC LOCK FILE DIFFERENCES ==="
              echo "Saving spec lock file differences to to build/spec_lock_file_differences.log"
              cp "$FLS_DIFF_FILE" build/spec_lock_file_differences.txt
            fi

            exit 1
          else
            # Even if there's no error, still check for FLS differences file
            FLS_DIFF_FILE=$(grep -o '/tmp/fls_diff_[^ ]*\.txt' build/build.log | head -1)
            if [ ! -z "$FLS_DIFF_FILE" ] && [ -f "$FLS_DIFF_FILE" ]; then
              echo "=== SPEC LOCK FILE DIFFERENCES, NO BUILD ERROR ==="
              echo "Saving spec lock file differences to to build/spec_lock_file_differences.log"
              cp "$FLS_DIFF_FILE" build/spec_lock_file_differences.txt
            fi
          fi
      - name: Archive build artifacts
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: build-artifacts
          path: build
          retention-days: 7
          compression-level: 6  # Default compression level for a good balance of speed and size

  check_typos:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Install typos
        run: cargo install typos-cli
      - name: Check for typos
        run: typos