docs: design updates for Generated API Docs (#308)

envoyproxy · Feb 9, 2025 · 9527e7f · 9527e7f
1 parent 2ddeb70
commit 9527e7f
Show file tree

Hide file tree

Showing 13 changed files with 1,459 additions and 538 deletions.
diff --git a/Makefile b/Makefile
@@ -89,13 +89,12 @@ apigen: controller-gen
 .PHONY: apidoc
 apidoc: crd-ref-docs
 	@$(CRD_REF_DOCS) \
-    	--source-path=api/v1alpha1 \
-    	--config=site/crd-ref-docs/config.yaml \
-    	--templates-dir=site/crd-ref-docs/templates \
-    	--output-path=API.md \
-    	--max-depth 20 \
-    	--output-path site/docs/api.md \
-    	--renderer=markdown
+		--source-path=api/v1alpha1 \
+		--config=site/crd-ref-docs/config-core.yaml \
+		--templates-dir=site/crd-ref-docs/templates \
+		--max-depth 20 \
+		--output-path site/docs/api/api.mdx \
+		--renderer=markdown
 
 # This runs all necessary steps to prepare for a commit.
 .PHONY: precommit

diff --git a/api/v1alpha1/api.go b/api/v1alpha1/api.go
@@ -99,20 +99,21 @@ type AIGatewayRouteSpec struct {
 	// metadata per HTTP request. The namespaced key is "io.envoy.ai_gateway",
 	//
 	// For example, let's say we have the following LLMRequestCosts configuration:
-	//
+	// ```yaml
 	//	llmRequestCosts:
 	//	- metadataKey: llm_input_token
 	//	  type: InputToken
 	//	- metadataKey: llm_output_token
 	//	  type: OutputToken
 	//	- metadataKey: llm_total_token
 	//	  type: TotalToken
-	//
+	// ```
 	// Then, with the following BackendTrafficPolicy of Envoy Gateway, you can have three
 	// rate limit buckets for each unique x-user-id header value. One bucket is for the input token,
 	// the other is for the output token, and the last one is for the total token.
 	// Each bucket will be reduced by the corresponding token usage captured by the AI Gateway filter.
 	//
+	// ```yaml
 	//	apiVersion: gateway.envoyproxy.io/v1alpha1
 	//	kind: BackendTrafficPolicy
 	//	metadata:
@@ -182,7 +183,7 @@ type AIGatewayRouteSpec struct {
 	//	              metadata:
 	//	                namespace: io.envoy.ai_gateway
 	//	                key: llm_total_token
-	//
+	// ```
 	// +optional
 	// +kubebuilder:validation:MaxItems=36
 	LLMRequestCosts []LLMRequestCost `json:"llmRequestCosts,omitempty"`

diff --git a/manifests/charts/ai-gateway-helm/crds/aigateway.envoyproxy.io_aigatewayroutes.yaml b/manifests/charts/ai-gateway-helm/crds/aigateway.envoyproxy.io_aigatewayroutes.yaml
@@ -164,15 +164,15 @@ spec:
                   the LLM-related request, notably the token usage.\nThe AI Gateway
                   filter will capture each specified number and store it in the Envoy's
                   dynamic\nmetadata per HTTP request. The namespaced key is \"io.envoy.ai_gateway\",\n\nFor
-                  example, let's say we have the following LLMRequestCosts configuration:\n\n\tllmRequestCosts:\n\t-
+                  example, let's say we have the following LLMRequestCosts configuration:\n```yaml\n\tllmRequestCosts:\n\t-
                   metadataKey: llm_input_token\n\t  type: InputToken\n\t- metadataKey:
                   llm_output_token\n\t  type: OutputToken\n\t- metadataKey: llm_total_token\n\t
-                  \ type: TotalToken\n\nThen, with the following BackendTrafficPolicy
+                  \ type: TotalToken\n```\nThen, with the following BackendTrafficPolicy
                   of Envoy Gateway, you can have three\nrate limit buckets for each
                   unique x-user-id header value. One bucket is for the input token,\nthe
                   other is for the output token, and the last one is for the total
                   token.\nEach bucket will be reduced by the corresponding token usage
-                  captured by the AI Gateway filter.\n\n\tapiVersion: gateway.envoyproxy.io/v1alpha1\n\tkind:
+                  captured by the AI Gateway filter.\n\n```yaml\n\tapiVersion: gateway.envoyproxy.io/v1alpha1\n\tkind:
                   BackendTrafficPolicy\n\tmetadata:\n\t  name: some-example-token-rate-limit\n\t
                   \ namespace: default\n\tspec:\n\t  targetRefs:\n\t  - group: gateway.networking.k8s.io\n\t
                   \    kind: HTTPRoute\n\t     name: usage-rate-limit\n\t  rateLimit:\n\t
@@ -204,7 +204,7 @@ spec:
                   \           unit: Hour\n\t          cost:\n\t            request:\n\t
                   \             from: Number\n\t              number: 0\n\t            response:\n\t
                   \             from: Metadata\n\t              metadata:\n\t                namespace:
-                  io.envoy.ai_gateway\n\t                key: llm_total_token"
+                  io.envoy.ai_gateway\n\t                key: llm_total_token\n```"
                 items:
                   description: LLMRequestCost configures each request cost.
                   properties:

diff --git a/site/crd-ref-docs/config.yaml → site/crd-ref-docs/config-core.yaml b/site/crd-ref-docs/config.yaml → site/crd-ref-docs/config-core.yaml
@@ -34,3 +34,10 @@ render:
     - name: ExtProc
       package: github.com/envoyproxy/gateway/api/v1alpha1
       link: https://gateway.envoyproxy.io/docs/api/extension_types/#extproc
+    - name: OIDC
+      package: github.com/envoyproxy/gateway/api/v1alpha1
+      link: https://gateway.envoyproxy.io/docs/api/extension_types/#oidc
+
+navigation:
+  includeTOC: true
+  includeBackToTopLinks: true
diff --git a/site/crd-ref-docs/templates/gv_details.tpl b/site/crd-ref-docs/templates/gv_details.tpl
@@ -5,15 +5,51 @@
 
 {{ $gv.Doc }}
 
-{{- if $gv.Kinds  }}
-### Resource Types
+{{- if $gv.Kinds }}
+## Resource Kinds
+
+### Available Kinds
 {{- range $gv.SortedKinds }}
 - {{ $gv.TypeForKind . | markdownRenderTypeLink }}
 {{- end }}
-{{ end }}
 
-{{ range $gv.SortedTypes }}
+### Kind Definitions
+{{- range $gv.SortedKinds }}
+{{- $type := $gv.TypeForKind . }}
+{{ template "type" $type }}
+{{- end }}
+{{- end }}
+
+{{- if $gv.Types }}
+## Supporting Types
+
+### Available Types
+{{- range $gv.SortedTypes }}
+{{- $type := . }}
+{{- $isKind := false }}
+{{- range $gv.Kinds }}
+{{- if eq . $type.Name }}
+{{- $isKind = true }}
+{{- end }}
+{{- end }}
+{{- if not $isKind }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+### Type Definitions
+{{- range $gv.SortedTypes }}
+{{- $type := . }}
+{{- $isKind := false }}
+{{- range $gv.Kinds }}
+{{- if eq . $type.Name }}
+{{- $isKind = true }}
+{{- end }}
+{{- end }}
+{{- if not $isKind }}
 {{ template "type" . }}
-{{ end }}
+{{- end }}
+{{- end }}
+{{- end }}
 
 {{- end -}}
diff --git a/site/crd-ref-docs/templates/gv_list.tpl b/site/crd-ref-docs/templates/gv_list.tpl
@@ -5,13 +5,10 @@
 ---
 id: api_references
 title: API Reference
+toc_min_heading_level: 2
+toc_max_heading_level: 4
 ---
 
-## Packages
-{{- range $groupVersions }}
-- {{ markdownRenderGVLink . }}
-{{- end }}
-
 {{ range $groupVersions }}
 {{ template "gvDetails" . }}
 {{ end }}

diff --git a/site/crd-ref-docs/templates/type.tpl b/site/crd-ref-docs/templates/type.tpl
@@ -4,38 +4,63 @@
 
 #### {{ $type.Name }}
 
-{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
-
-{{ $type.Doc }}
-
-{{ if $type.References -}}
-_Appears in:_
+{{ if $type.IsAlias }}**Underlying type:** {{ markdownRenderTypeLink $type.UnderlyingType  }}{{ end }}
+{{ if $type.References }}
+**Appears in:**
 {{- range $type.SortedReferences }}
 - {{ markdownRenderTypeLink . }}
 {{- end }}
 {{- end }}
 
+{{ $type.Doc }}
+
 {{ if $type.Members -}}
-| Field | Type | Required | Description |
-| ---   | ---  | ---      | ---         |
+
+##### Fields
+
 {{ if $type.GVK -}}
-| `apiVersion` | _string_ | |`{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
-| `kind` | _string_ | |`{{ $type.GVK.Kind }}`
-{{ end -}}
+<ApiField
+  name="apiVersion"
+  type="String"
+  required="true"
+  description="We are on version <code>{{ $type.GVK.Group }}/{{ $type.GVK.Version }}</code> of the API."
+/>
+
+<ApiField
+  name="kind"
+  type="String"
+  required="true"
+  description="This is a <code>{{ $type.GVK.Kind }}</code> resource"
+/>
+{{- end }}
 
 {{ range $type.Members -}}
-{{- with .Markers.notImplementedHide -}}
-{{- else -}}
-| `{{ .Name  }}` | _{{ markdownRenderType .Type }}_ | {{ with .Markers.optional }} {{ "false" }} {{ else }} {{ "true" }} {{end}} | {{ template "type_members" . }} |
-{{ end -}}
-{{- end -}}
-{{- end -}}
+{{- if not .Markers.notImplementedHide -}}
+<ApiField
+  name="{{ .Name }}"
+  type="{{ markdownRenderType .Type }}"
+  required="{{ if .Markers.optional }}false{{ else }}true{{ end }}"
+  {{- if .Default }}
+  defaultValue="{{ .Default }}"
+  {{- end }}
+  description="{{ template "type_members" . }}"
+/>
+{{- end }}
+{{- end }}
+{{- end }}
+
 {{ if $type.EnumValues -}}
-| Value | Description |
-| ----- | ----------- |
+##### Possible Values
+
 {{ range $type.EnumValues -}}
-| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
-{{ end -}}
-{{- end -}}
-{{- end -}}
+<ApiField
+  name="{{ .Name }}"
+  type="enum"
+  required="false"
+  description="{{ markdownRenderFieldDoc .Doc }}"
+/>
+{{- end }}
+{{- end }}
+
+{{- end }}
 {{- end -}}
diff --git a/site/crd-ref-docs/templates/type_members.tpl b/site/crd-ref-docs/templates/type_members.tpl
@@ -3,6 +3,6 @@
 {{- if eq $field.Name "metadata" -}}
 Refer to Kubernetes API documentation for fields of `metadata`.
 {{- else -}}
-{{ markdownRenderFieldDoc $field.Doc }}
+{{ markdownRenderFieldDoc $field.Doc | replace "\"" "`" }}
 {{- end -}}
 {{- end -}}