Generate API reference docs for agentgateway #16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # 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 |