name: Documentation

on:
  push:
    paths:
      - ".gitea/workflows/documentation.yml"
      - "Cargo.lock"
      - "Cargo.toml"
      - "README.md"
      - "api/**"
      - "crates/**"
      - "docs/**"
      - "programs/**"
      - "tools/ci-matrix/**"
      - "tools/generate_api_shims.py"
      - "tools/install_openjpeg_2_5_4.sh"
  pull_request:
    paths:
      - ".gitea/workflows/documentation.yml"
      - "Cargo.lock"
      - "Cargo.toml"
      - "README.md"
      - "api/**"
      - "crates/**"
      - "docs/**"
      - "programs/**"
      - "tools/ci-matrix/**"
      - "tools/generate_api_shims.py"
      - "tools/install_openjpeg_2_5_4.sh"
  workflow_dispatch:

jobs:
  documentation:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    env:
      OPENJPEG_PREFIX: /tmp/metacrate-openjpeg-${{ github.run_id }}
      PKG_CONFIG_PATH: /tmp/metacrate-openjpeg-${{ github.run_id }}/lib/pkgconfig
      LD_LIBRARY_PATH: /tmp/metacrate-openjpeg-${{ github.run_id }}/lib
      FORCE_SKIA_BINARIES_DOWNLOAD: "1"
      CARGO_BUILD_JOBS: 1
      CARGO_INCREMENTAL: 0
    steps:
      - uses: actions/checkout@v4

      - name: Install native documentation prerequisites
        run: |
          sudo apt-get update
          sudo apt-get install --yes build-essential clang cmake curl ninja-build \
            pkg-config python3 libfontconfig1-dev libfreetype6-dev libopus-dev
          tools/install_openjpeg_2_5_4.sh "$OPENJPEG_PREFIX"

      - name: Install Rust 1.97 toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: 1.97.0
          components: rustfmt

      - name: Check formatting
        run: cargo fmt --all -- --check

      - name: Verify documentation coverage report
        run: |
          cargo run --locked -p metacrate-ci-matrix -- documentation-report
          git diff --exit-code -- api/DOCUMENTATION-COVERAGE.md
          cargo run --locked -p metacrate-ci-matrix -- documentation-audit --evidence ci/evidence/documentation-audit.json

      - name: Build warning-free workspace documentation
        env:
          RUSTDOCFLAGS: "-D warnings"
        run: cargo doc --workspace --no-deps --locked -j 1

      - name: Compile guide snippets and examples
        run: |
          cargo test --locked -p libremetaverse --doc -j 1
          cargo test --locked -p libremetaverse --examples -j 1
          cargo run --locked -p libremetaverse --example offline_client
          cargo run --locked -p libremetaverse --example cancellation

      - name: Verify documented program quick starts
        run: cargo test --locked -p libremetaverse-programs --tests -j 1

      - name: Upload documentation evidence
        uses: actions/upload-artifact@v4
        with:
          name: documentation-evidence
          path: ci/evidence/documentation-audit.json
          if-no-files-found: error