docs.yml

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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ruby/setup-ruby@762794c140bbeda0f1224786aa33b4b46783a6c1 # v1.326.0
        with:
          bundler-cache: true
      - uses: swift-actions/setup-swift@364295d9c23900ce04d4e5cc708387921b4e50f9 # v3.0.0-beta.1
        with:
          swift-version: "6.3.3"
          skip-verify-signature: true
      - name: Build SwiftLint and SourceKitten
        uses: ./.github/actions/bazel-linux
        with:
          mode: build
          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@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          key: ubuntu-24.04-spm-${{ steps.swift_version.outputs.version }}-${{ hashFiles('Package.resolved', 'Package.swift') }}
          restore-keys: ubuntu-24.04-spm-${{ steps.swift_version.outputs.version }}-
          path: .build
      - name: Generate documentation
        run: |
          swiftly_lib_dir=$(swiftly use -p)/usr/lib
          export LD_LIBRARY_PATH="$swiftly_lib_dir:$LD_LIBRARY_PATH"
          export PATH="$SWIFTLY_BIN_DIR:$PATH"
          make docs_linux
      - name: Process documentation violations
        run: |
          if [ -f "docs/undocumented.json" ]; then
            violation_count=$(ruby -rjson -e "puts JSON.parse(File.read('docs/undocumented.json'))['warnings'].length")

            if [ "$violation_count" -gt 0 ]; then
              echo "⚠️ Found $violation_count documentation violations"

              # Create GitHub annotations for each violation
              ruby -rjson -e "
                data = JSON.parse(File.read('docs/undocumented.json'))
                data['warnings'].each do |warning|
                  # Convert absolute path to relative path for the annotation
                  file_path = warning['file'].gsub('/home/runner/work/SwiftLint/SwiftLint/', '')
                  puts \"::error file=#{file_path},line=#{warning['line']}::Undocumented #{warning['symbol_kind'].split('.').last}: #{warning['symbol']}\"
                end
              "

              exit 1
            else
              echo "✅ No documentation violations found"
            fi
          else
            echo "❌ undocumented.json file not found"
          fi
      - name: Upload documentation
        if: github.event_name == 'push'
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs

  deploy-docs:
    name: Deploy
    runs-on: ubuntu-slim
    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@v5