docs: improve api type members (#2544)

* docs: improve api type members Signed-off-by: zirain <[email protected]> * nits Signed-off-by: zirain <[email protected]> --------- Signed-off-by: zirain <[email protected]>
envoyproxy · Feb 1, 2024 · 0676f04 · 0676f04
1 parent 3e99199
commit 0676f04
Show file tree

Hide file tree

Showing 7 changed files with 645 additions and 568 deletions.
diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
diff --git a/tools/crd-ref-docs/templates/README b/tools/crd-ref-docs/templates/README
@@ -0,0 +1 @@
+Original from https://github.com/elastic/crd-ref-docs/tree/9a3105b6ca763ea03393fa6f396046ad7b5d4e38/templates/markdown
diff --git a/tools/crd-ref-docs/templates/gv_details.tpl b/tools/crd-ref-docs/templates/gv_details.tpl
@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+## {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+### Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}
diff --git a/tools/crd-ref-docs/templates/gv_list.tpl b/tools/crd-ref-docs/templates/gv_list.tpl
@@ -0,0 +1,15 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+# API Reference
+
+## Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}
diff --git a/tools/crd-ref-docs/templates/type.tpl b/tools/crd-ref-docs/templates/type.tpl
@@ -0,0 +1,33 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if markdownShouldRenderType $type -}}
+
+#### {{ $type.Name }}
+
+{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.References -}}
+_Appears in:_
+{{- range $type.SortedReferences }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.Members -}}
+| Field | Type | Description |
+| --- | --- | --- |
+{{ if $type.GVK -}}
+| `apiVersion` | _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
+| `kind` | _string_ | `{{ $type.GVK.Kind }}`
+{{ end -}}
+
+{{ range $type.Members -}}
+| `{{ .Name  }}` | _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} |
+{{ end -}}
+
+{{ end -}}
+
+{{- end -}}
+{{- end -}}
diff --git a/tools/crd-ref-docs/templates/type_members.tpl b/tools/crd-ref-docs/templates/type_members.tpl
@@ -0,0 +1,8 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{- else -}}
+{{ markdownRenderFieldDoc $field.Doc }}
+{{- end -}}
+{{- end -}}
diff --git a/tools/make/docs.mk b/tools/make/docs.mk
@@ -46,6 +46,7 @@ docs-api-gen: $(tools/crd-ref-docs)
 	$(tools/crd-ref-docs) \
 	--source-path=api/v1alpha1 \
 	--config=tools/crd-ref-docs/config.yaml \
+	--templates-dir=tools/crd-ref-docs/templates \
 	--output-path=site/content/en/latest/api/extension_types.md \
 	--max-depth 10 \
 	--renderer=markdown
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Original from https://github.com/elastic/crd-ref-docs/tree/9a3105b6ca763ea03393fa6f396046ad7b5d4e38/templates/markdown