reference-docs.yaml

# Generates Kubernetes API reference docs from agentgateway/agentgateway.
# Version configuration is read directly from hugo.yaml (params.sections.standalone.versions).
# Released versions resolve the latest matching tag dynamically via tagPrefix derived from the
# version string (e.g. 1.0.x -> v1.0.*). The "main" linkVersion uses the main branch directly.
#
# workflow_dispatch inputs:
#   doc_version: a specific version (e.g. 1.0.x), or "all" to run for every version in hugo.yaml
name: Generate API reference docs for agentgateway

on:
  release:
    types: [created]
  workflow_dispatch:
    inputs:
      doc_version:
        description: 'Doc version to generate (must match a version in hugo.yaml), e.g. 1.0.x, or "all"'
        required: true
        default: '1.0.x'

jobs:
  setup:
    name: Setup and validate
    runs-on: ubuntu-22.04
    outputs:
      matrix: ${{ steps.build_matrix.outputs.matrix }}
    steps:
      - name: Checkout website repo
        uses: actions/checkout@v4
        with:
          path: website
          fetch-depth: 1

      - name: Build version matrix
        id: build_matrix
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          if [[ "${{ github.event_name }}" == "release" ]]; then
            input_version="1.0.x"
          else
            input_version="${{ inputs.doc_version }}"
          fi

          # Read all versions from hugo.yaml
          all_versions=$(python3 -c "
          import yaml, json, sys
          with open('website/hugo.yaml') as f:
              cfg = yaml.safe_load(f)
          versions = cfg['params']['sections']['standalone']['versions']
          print(json.dumps(versions))
          ")

          # Determine which versions to process
          if [[ "$input_version" == "all" ]]; then
            target_versions="$all_versions"
          else
            target_versions=$(python3 -c "
          import json, sys
          versions = json.loads(sys.argv[1])
          entry = next((v for v in versions if v['version'] == sys.argv[2]), None)
          if not entry:
              valid = [v['version'] for v in versions]
              print(f'Error: version {sys.argv[2]} not found in hugo.yaml. Valid versions: {valid}', file=sys.stderr)
              sys.exit(1)
          print(json.dumps([entry]))
            " "$all_versions" "$input_version")
          fi

          # Resolve the git ref for each version and build the matrix
          matrix_items='[]'
          while IFS= read -r entry; do
            doc_version=$(echo "$entry" | jq -r '.version')
            link_version=$(echo "$entry" | jq -r '.linkVersion')

            if [[ "$link_version" == "main" ]]; then
              echo "Checking branch: main"
              if ! git ls-remote --heads https://github.com/agentgateway/agentgateway.git refs/heads/main | grep -q main; then
                echo "Error: main branch not found in agentgateway/agentgateway"
                exit 1
              fi
              ref="main"
            else
              TAG_PREFIX=$(echo "$doc_version" | sed 's/\.[^.]*$/\./' | sed 's/^/v/')
              echo "Resolving latest tag with prefix ${TAG_PREFIX}..."
              ref=$(gh api repos/agentgateway/agentgateway/tags --paginate \
                --jq '.[].name' | grep "^${TAG_PREFIX}" | sort -V | tail -1)
              if [[ -z "$ref" ]]; then
                echo "Error: no tags found matching prefix ${TAG_PREFIX} in agentgateway/agentgateway"
                exit 1
              fi
              echo "Resolved ${doc_version} (${link_version}) -> ${ref}"
            fi

            item=$(jq -n \
              --arg dv "$doc_version" \
              --arg lv "$link_version" \
              --arg r "$ref" \
              '{doc_version: $dv, link_version: $lv, ref: $r}')
            matrix_items=$(echo "$matrix_items" | jq --argjson item "$item" '. + [$item]')
          done < <(echo "$target_versions" | jq -c '.[]')

          matrix=$(echo "$matrix_items" | jq -c '{include: .}')
          echo "matrix=${matrix}" >> $GITHUB_OUTPUT
          echo "Matrix: $matrix"

  api-docs:
    name: Generate API docs (${{ matrix.link_version }})
    runs-on: ubuntu-22.04
    needs: setup
    strategy:
      matrix: ${{ fromJson(needs.setup.outputs.matrix) }}
      fail-fast: false
    env:
      GOTOOLCHAIN: auto
    steps:
      - name: Checkout website repo
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          path: website
          fetch-depth: 0

      - name: Setup Go for docs generation
        uses: actions/setup-go@v6
        with:
          go-version: 1.25.7
          cache: false

      - name: Checkout agentgateway source repository
        uses: actions/checkout@v4
        with:
          repository: agentgateway/agentgateway
          token: ${{ secrets.GITHUB_TOKEN }}
          path: agentgateway
          ref: ${{ matrix.ref }}

      - name: Generate agentgateway API docs
        run: |
          pushd website || exit 1

          LINK_VERSION="${{ matrix.link_version }}"
          API_FILE="api-${LINK_VERSION}.md"

          # API types live in agentgateway controller/api/v1alpha1/agentgateway/
          echo "Generating agentgateway API docs from controller/api/v1alpha1/agentgateway/"
          go run github.com/elastic/crd-ref-docs@latest \
            --source-path="$PWD/../agentgateway/controller/api/v1alpha1/agentgateway/" \
            --renderer=markdown \
            --output-path ./ \
            --max-depth=100 \
            --config=scripts/crd-ref-docs-config.yaml

          if [ ! -f "./out.md" ]; then
            echo "Error: API docs generation failed - out.md not found"
            exit 1
          fi

          TARGET_DIR="assets/agw-docs/pages/reference/api"
          mkdir -p "$TARGET_DIR"
          TARGET_FILE="${TARGET_DIR}/${API_FILE}"

          echo "Processing API docs -> ${TARGET_FILE}"

          # Remove first 3 lines and fix common artifacts
          tail -n +4 "./out.md" | \
            sed 's/Required: {}/Required/g; s/Optional: {}/Optional/g; /^# API Reference$/,/^$/d' \
            > "$TARGET_FILE"

          # Simplify complex struct types
          sed -i.bak -E 's/_Underlying type:_ _\[?struct\{[^}]*\}[]\)]*(\\([^)]+\\))?_/_Underlying type:_ _struct_/g' "$TARGET_FILE"
          rm -f "$TARGET_FILE.bak"

          rm "./out.md"
          echo "API docs generated successfully at $TARGET_FILE"

          popd || exit 1

      - name: Generate shared types documentation
        run: |
          LINK_VERSION="${{ matrix.link_version }}"
          TARGET_FILE="website/assets/agw-docs/pages/reference/api/api-${LINK_VERSION}.md"
          SHARED_DIR="agentgateway/controller/api/v1alpha1/shared"
          AGENTGATEWAY_SOURCE_DIR="agentgateway/controller/api/v1alpha1/agentgateway"
          if [ -f "$TARGET_FILE" ]; then
            echo "Generating shared types documentation for api-${LINK_VERSION}.md..."
            python3 website/scripts/generate-shared-types.py \
              "$SHARED_DIR" \
              "$TARGET_FILE" \
              "$AGENTGATEWAY_SOURCE_DIR"
          else
            echo "API doc file not found - skipping shared types"
          fi

      - name: Generate Helm and metrics docs
        run: |
          LINK_VERSION="${{ matrix.link_version }}" \
          WEBSITE_DIR="website" \
          KGATEWAY_DIR="agentgateway/controller" \
          python3 website/scripts/generate-ref-docs.py

      # Create PR: needs "Allow GitHub Actions to create and approve pull requests" (Settings → Actions)
      # or a repo secret CREATE_PR_TOKEN (PAT with pull_requests: write).
      - name: Create PR for website repo
        uses: peter-evans/create-pull-request@v7
        id: create-pr
        with:
          path: website
          base: main
          body: |
            Generate reference documentation for agentgateway (${{ matrix.link_version }}).

            Source: agentgateway/agentgateway at `${{ matrix.ref }}`.
            Updates API reference (including shared types such as CEL expression), Helm (agentgateway + agentgateway-crds), and control plane metrics for the ${{ matrix.link_version }} version.

            This PR was created automatically by the reference-docs workflow.

            Workflow run: https://github.com/agentgateway/website/actions/runs/${{ github.run_id }}
          branch: ref-docs-${{ matrix.link_version }}
          commit-message: 'docs: update API (incl. shared types), Helm, and metrics docs from agentgateway ${{ matrix.ref }}'
          committer: GitHub Action <action@github.com>
          delete-branch: true
          title: '[Automated] Update reference docs (${{ matrix.link_version }}) from agentgateway ${{ matrix.ref }}'
          token: ${{ secrets.CREATE_PR_TOKEN || secrets.GITHUB_TOKEN }}

      - name: Output PR URL
        run: |
          if [ -n "${{ steps.create-pr.outputs.pull-request-url }}" ]; then
            echo "PR created: ${{ steps.create-pr.outputs.pull-request-url }}"
          else
            echo "No changes detected - PR not created"
          fi