docs.yaml

on:
  push:
  pull_request:
  merge_group:
  schedule: # Trigger a job on default branch at 4AM PST everyday
    - cron: "0 11 * * *"

name: Docs

env:
  RUSTDOCFLAGS: -D warnings

jobs:
  docs:
    name: Docs
    runs-on: windows-latest
    strategy:
      matrix:
        wdk:
          - Microsoft.WindowsWDK.10.0.22621 # NI WDK

        llvm:
          - 17.0.6

        rust_toolchain:
          - stable
          - beta
          - nightly

        cargo_profile:
          - dev
          - release

        target_triple:
          - x86_64-pc-windows-msvc
          - aarch64-pc-windows-msvc

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Install Winget
        uses: ./.github/actions/winget-install
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Install LLVM ${{ matrix.llvm }}
        run: |
          if ((Get-WinGetPackage -Id LLVM -Source winget -MatchOption Equals).InstalledVersion -eq '${{ matrix.llvm }}') {
            Write-Host "LLVM ${{ matrix.llvm }} is already installed."
          } else {
            Write-Host "Installing LLVM ${{ matrix.llvm }}..."
            Install-WinGetPackage -Id LLVM.LLVM -Version ${{ matrix.llvm }} -Source winget -MatchOption Equals -Mode Silent -Force
          }
          clang --version

      - name: Install WDK (${{ matrix.wdk }})
        run: |
          if ((Get-WinGetPackage -Id ${{ matrix.wdk }} -Source winget -MatchOption Equals).Id -eq '${{ matrix.wdk }}') {
            Write-Host "${{ matrix.wdk }} is already installed. Attempting to update..."
            Update-WinGetPackage -Id ${{ matrix.wdk }} -Source winget -MatchOption Equals -Mode Silent -Force
          } else {
            Write-Host "Installing ${{ matrix.wdk }}..."
            Install-WinGetPackage -Id ${{ matrix.wdk }} -Source winget -MatchOption Equals -Mode Silent -Force
          }

      - name: Install Rust Toolchain (${{ matrix.rust_toolchain }})
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ matrix.rust_toolchain }}
          targets: ${{ matrix.target_triple }}

      - name: Run Cargo Doc
        # proc-macro crates must be excluded to avoid cargo doc bug: https://github.com/rust-lang/cargo/issues/10368
        run: cargo +${{ matrix.rust_toolchain }} doc --locked --profile ${{ matrix.cargo_profile }} --target ${{ matrix.target_triple }} --workspace --exclude wdk-macros

      - name: Run Cargo Doc (--features nightly)
        if: matrix.rust_toolchain == 'nightly'
        # proc-macro crates must be excluded to avoid cargo doc bug: https://github.com/rust-lang/cargo/issues/10368
        run: cargo +${{ matrix.rust_toolchain }} doc --locked --profile ${{ matrix.cargo_profile }} --target ${{ matrix.target_triple }} --workspace --exclude wdk-macros --features nightly

      - name: Run Cargo Doc w/ proc-macro crates
        if: matrix.target_triple == 'x86_64-pc-windows-msvc'
        # cargo doc can only generate documentation for proc-macro crates when --target is not specified due to a cargo doc bug: https://github.com/rust-lang/cargo/issues/7677
        run: cargo +${{ matrix.rust_toolchain }} doc --locked --profile ${{ matrix.cargo_profile }}

      - name: Run Cargo Doc w/ proc-macro crates (--features nightly)
        if: ${{ matrix.target_triple == 'x86_64-pc-windows-msvc' && matrix.rust_toolchain == 'nightly' }}
        # cargo doc can only generate documentation for proc-macro crates when --target is not specified due to a cargo doc bug: https://github.com/rust-lang/cargo/issues/7677
        run: cargo +${{ matrix.rust_toolchain }} doc --locked --profile ${{ matrix.cargo_profile }} --features nightly