name: Documentation

on:
  push:
    branches: [main]
  pull_request:

jobs:
  create-docs:
    name: Create
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
        with:
          persist-credentials: false
      - uses: ruby/setup-ruby@44511735964dcb71245e7e55f72539531f7bc0eb # v1.257.0
        with:
          bundler-cache: true
      - name: Build SwiftLint and SourceKitten
        uses: ./.github/actions/bazel-linux-build
        with:
          target: "//:swiftlint @SourceKittenFramework//:sourcekitten"
        env:
          CI_BAZELRC_FILE_CONTENT: ${{ secrets.CI_BAZELRC_FILE_CONTENT }}
      - name: Get Swift version
        id: swift_version
        run: echo "version=$(swift --version | grep '[5-9]\.[0-9]\+\.[0-9]' -o | head -1)" >> "$GITHUB_OUTPUT"
      - uses: actions/cache@v4
        with:
          key: ${{ runner.os }}-spm-${{ steps.swift_version.outputs.version }}-${{ hashFiles('Package.resolved', 'Package.swift') }}
          restore-keys: ${{ runner.os }}-spm-${{ steps.swift_version.outputs.version }}-
          path: .build
      - name: Generate documentation
        run: |
          export PATH="/usr/share/swift/usr/bin:$PATH"
          make docs_linux
      - name: Validate documentation coverage
        run: |
          if ruby -rjson -e "j = JSON.parse(File.read('docs/undocumented.json')); exit j['warnings'].length != 0"; then
            echo "Undocumented declarations:"
            cat docs/undocumented.json
            exit 1
          fi
      - name: Upload documentation
        if: github.event_name == 'push'
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs

  deploy-docs:
    name: Deploy
    runs-on: ubuntu-24.04
    needs: create-docs
    if: github.event_name == 'push'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy documentation
        id: deployment
        uses: actions/deploy-pages@v4