Skip to content

Commit c950d4e

Browse files
artbergerartberger
committed
api workflow draft 1
Signed-off-by: Art Berger <art.berger@solo.io>
1 parent f4391ed commit c950d4e

3 files changed

Lines changed: 213 additions & 0 deletions

File tree

‎.github/workflows/crd-ref-docs-config.yaml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
processor:
2+
ignoreGroupVersions:
3+
- gateway.networking.k8s.io/v1
4+
- gateway.networking.k8s.io/v1alpha2
5+
- gateway.networking.k8s.io/v1beta1
6+
ignoreTypes:
7+
- metav1.ObjectMeta
8+
- metav1.TypeMeta
9+
- metav1.ListMeta
10+
11+
renderer:
12+
kubernetesVersion: "1.31"

‎.github/workflows/reference-docs.yaml‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Generates Kubernetes API reference docs from kgateway-dev/kgateway.
2+
# Version-to-branch and output file mapping is read from .github/workflows/versions.json.
3+
# Each entry can include apiFile and kgatewayRef; add new versions there without editing this workflow.
4+
name: Generate API reference docs for agentgateway
5+
6+
on:
7+
release:
8+
types: [created]
9+
workflow_dispatch:
10+
inputs:
11+
doc_version:
12+
description: 'Doc version to generate (must exist in .github/workflows/versions.json), e.g. 2.2.x, 2.3.x'
13+
required: true
14+
default: '2.2.x'
15+
16+
jobs:
17+
setup:
18+
name: Setup and validate
19+
runs-on: ubuntu-22.04
20+
outputs:
21+
ref: ${{ steps.kgateway_ref.outputs.ref }}
22+
directory: ${{ steps.version_variables.outputs.directory }}
23+
api_file: ${{ steps.version_variables.outputs.api_file }}
24+
doc_version: ${{ steps.version_variables.outputs.doc_version }}
25+
steps:
26+
- name: Checkout website repo
27+
uses: actions/checkout@v4
28+
with:
29+
path: website
30+
fetch-depth: 1
31+
32+
- name: Resolve version from versions.json
33+
id: version_variables
34+
run: |
35+
VERSIONS_FILE="website/.github/workflows/versions.json"
36+
if [[ "${{ github.event_name }}" == "release" ]]; then
37+
doc_version="2.2.x"
38+
else
39+
doc_version="${{ inputs.doc_version }}"
40+
fi
41+
echo "doc_version=${doc_version}" >> $GITHUB_OUTPUT
42+
ENTRY=$(jq -r --arg v "${doc_version}" '.[] | select(.version == $v) | @base64' "$VERSIONS_FILE" | head -1)
43+
if [[ -z "$ENTRY" ]]; then
44+
echo "Error: version '${doc_version}' not found in ${VERSIONS_FILE}. Valid versions:"
45+
jq -r '.[].version' "$VERSIONS_FILE"
46+
exit 1
47+
fi
48+
DECODED=$(echo "$ENTRY" | base64 -d)
49+
directory=$(echo "$DECODED" | jq -r '.linkVersion')
50+
api_file=$(echo "$DECODED" | jq -r '.apiFile')
51+
kgateway_ref=$(echo "$DECODED" | jq -r '.kgatewayRef')
52+
if [[ "$directory" == "null" || "$directory" == "" ]]; then
53+
echo "Error: ${VERSIONS_FILE} entry for ${doc_version} missing .linkVersion"
54+
exit 1
55+
fi
56+
if [[ "$api_file" == "null" || "$api_file" == "" ]]; then
57+
echo "Error: ${VERSIONS_FILE} entry for ${doc_version} missing .apiFile"
58+
exit 1
59+
fi
60+
if [[ "$kgateway_ref" == "null" || "$kgateway_ref" == "" ]]; then
61+
echo "Error: ${VERSIONS_FILE} entry for ${doc_version} missing .kgatewayRef"
62+
exit 1
63+
fi
64+
echo "directory=${directory}" >> $GITHUB_OUTPUT
65+
echo "api_file=${api_file}" >> $GITHUB_OUTPUT
66+
echo "kgateway_ref=${kgateway_ref}" >> $GITHUB_OUTPUT
67+
echo "Using ${doc_version}: directory=${directory}, api_file=${api_file}, kgatewayRef=${kgateway_ref}"
68+
69+
- name: Verify kgateway branch exists
70+
id: kgateway_ref
71+
env:
72+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
73+
run: |
74+
REF="${{ steps.version_variables.outputs.kgateway_ref }}"
75+
echo "Checking kgateway ref refs/heads/${REF}..."
76+
if ! git ls-remote --heads https://github.com/kgateway-dev/kgateway.git "refs/heads/${REF}" | grep -q "${REF}"; then
77+
echo "Error: kgateway branch ${REF} not found. Update .github/workflows/versions.json kgatewayRef for this version."
78+
exit 1
79+
fi
80+
echo "ref=${REF}" >> $GITHUB_OUTPUT
81+
echo "Using kgateway branch: ${REF}"
82+
83+
api-docs:
84+
name: Generate API docs
85+
runs-on: ubuntu-22.04
86+
needs: setup
87+
env:
88+
GOTOOLCHAIN: auto
89+
steps:
90+
- name: Checkout website repo
91+
uses: actions/checkout@v4
92+
with:
93+
token: ${{ secrets.GITHUB_TOKEN }}
94+
path: website
95+
fetch-depth: 0
96+
97+
- name: Setup Go for docs generation
98+
uses: actions/setup-go@v6
99+
with:
100+
go-version: 1.25.7
101+
cache: false
102+
103+
- name: Checkout kgateway source repository
104+
uses: actions/checkout@v4
105+
with:
106+
repository: kgateway-dev/kgateway
107+
token: ${{ secrets.GITHUB_TOKEN }}
108+
path: kgateway
109+
ref: ${{ needs.setup.outputs.ref }}
110+
111+
- name: Generate agentgateway API docs from kgateway
112+
run: |
113+
pushd website || exit 1
114+
115+
# API types live in kgateway api/v1alpha1/agentgateway/
116+
echo "Generating agentgateway API docs from kgateway api/v1alpha1/agentgateway/"
117+
go run github.com/elastic/crd-ref-docs@latest \
118+
--source-path="$PWD/../kgateway/api/v1alpha1/agentgateway/" \
119+
--renderer=markdown \
120+
--output-path ./ \
121+
--config=.github/workflows/crd-ref-docs-config.yaml
122+
123+
if [ ! -f "./out.md" ]; then
124+
echo "Error: API docs generation failed - out.md not found"
125+
exit 1
126+
fi
127+
128+
# Output to assets/agw-docs/pages/reference/api/api-22x.md or api-23x.md
129+
API_FILE="${{ needs.setup.outputs.api_file }}"
130+
TARGET_DIR="assets/agw-docs/pages/reference/api"
131+
mkdir -p "$TARGET_DIR"
132+
TARGET_FILE="${TARGET_DIR}/${API_FILE}"
133+
134+
echo "Processing API docs -> ${TARGET_FILE}"
135+
136+
# Remove first 3 lines and fix common artifacts
137+
tail -n +4 "./out.md" | \
138+
sed 's/Required: {}/Required/g; s/Optional: {}/Optional/g; /^# API Reference$/,/^$/d' \
139+
> "$TARGET_FILE"
140+
141+
# Simplify complex struct types
142+
sed -i.bak -E 's/_Underlying type:_ _\[?struct\{[^}]*\}[]\)]*(\([^)]+\))?_/_Underlying type:_ _struct_/g' "$TARGET_FILE"
143+
rm -f "$TARGET_FILE.bak"
144+
145+
rm "./out.md"
146+
echo "API docs generated successfully at $TARGET_FILE"
147+
148+
popd || exit 1
149+
150+
- name: Generate Helm and metrics docs
151+
run: |
152+
DOC_VERSION="${{ needs.setup.outputs.doc_version }}" \
153+
WEBSITE_DIR="website" \
154+
KGATEWAY_DIR="kgateway" \
155+
python3 website/.github/workflows/generate-ref-docs.py
156+
157+
- name: Create PR for website repo
158+
uses: peter-evans/create-pull-request@v7
159+
id: create-pr
160+
with:
161+
path: website
162+
base: main
163+
body: |
164+
Generate reference documentation for agentgateway (${{ needs.setup.outputs.api_file }}).
165+
166+
Source: kgateway-dev/kgateway at `${{ needs.setup.outputs.ref }}`.
167+
Updates API reference, Helm (agentgateway + agentgateway-crds), and control plane metrics for the ${{ needs.setup.outputs.directory }} version.
168+
169+
This PR was created automatically by the reference-docs workflow.
170+
171+
Workflow run: https://github.com/agentgateway/website/actions/runs/${{ github.run_id }}
172+
branch: ref-docs-${{ needs.setup.outputs.doc_version }}
173+
commit-message: 'docs: update API, Helm, and metrics docs from kgateway ${{ needs.setup.outputs.ref }}'
174+
committer: GitHub Action <action@github.com>
175+
delete-branch: true
176+
title: '[Automated] Update reference docs (${{ needs.setup.outputs.doc_version }}) from kgateway ${{ needs.setup.outputs.ref }}'
177+
token: ${{ secrets.GITHUB_TOKEN }}
178+
179+
- name: Output PR URL
180+
run: |
181+
if [ -n "${{ steps.create-pr.outputs.pull-request-url }}" ]; then
182+
echo "PR created: ${{ steps.create-pr.outputs.pull-request-url }}"
183+
else
184+
echo "No changes detected - PR not created"
185+
fi

‎.github/workflows/versions.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[
2+
{
3+
"version": "2.3.x",
4+
"linkVersion": "main",
5+
"url": "main",
6+
"apiFile": "api-23x.md",
7+
"kgatewayRef": "main"
8+
},
9+
{
10+
"version": "2.2.x",
11+
"linkVersion": "latest",
12+
"url": "latest",
13+
"apiFile": "api-22x.md",
14+
"kgatewayRef": "v2.2.x"
15+
}
16+
]

0 commit comments

Comments
 (0)