Improve apiref with experimental and ignored CRD description

Author: rikatz

.gitignore

@@ -57,3 +57,5 @@ go.work.sum
 .venv/
 release/
 site-src/reference/spec.md
+site-src/reference/specx.md
+

Makefile

@@ -198,10 +198,12 @@ api-ref-docs:
 	crd-ref-docs \
 		--source-path=${PWD}/apis \
 		--config=crd-ref-docs.yaml \
+		--templates-dir=${PWD}/hack/crd-ref-templates/ \
 		--renderer=markdown \
 		--output-path=${PWD}/site-src/reference/spec.md
 	crd-ref-docs \
 		--source-path=${PWD}/apisx \
 		--config=crd-ref-docs.yaml \
+		--templates-dir=${PWD}/hack/crd-ref-templates/ \
 		--renderer=markdown \
 		--output-path=${PWD}/site-src/reference/specx.md

hack/crd-ref-templates/README.md

@@ -0,0 +1,5 @@
+The templates contained in this directory were copied from https://github.com/elastic/crd-ref-docs/tree/master/templates/markdown
+and had the following modifications:
+
+- `type.tpl` - Adds an "experimental" marker in case the API field is marked as "experimental"
+- `type_members.tpl` - Removes the text between tags `<gateway:util:excludeFromCRD></gateway:util:excludeFromCRD>`

hack/crd-ref-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 -}}

hack/crd-ref-templates/gv_list.tpl

@@ -0,0 +1,15 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+# API Reference
+
+## Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

hack/crd-ref-templates/type.tpl

@@ -0,0 +1,49 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if markdownShouldRenderType $type -}}
+
+#### {{ $type.Name }}
+
+{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.Validation -}}
+_Validation:_
+{{- range $type.Validation }}
+- {{ . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.References -}}
+_Appears in:_
+{{- range $type.SortedReferences }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.Members -}}
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+{{ if $type.GVK -}}
+| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | |
+| `kind` _string_ | `{{ $type.GVK.Kind }}` | | |
+{{ end -}}
+
+{{ range $type.Members -}}
+| `{{ .Name  }}` {{- if contains "<gateway:experimental>" .Doc }} **Experimental** {{ end -}} _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
+{{ end -}}
+
+{{ end -}}
+
+{{ if $type.EnumValues -}} 
+| Field | Description |
+| --- | --- |
+{{ range $type.EnumValues -}}
+| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
+{{ end -}}
+{{ end -}}
+
+
+{{- end -}}
+{{- end -}}

hack/crd-ref-templates/type_members.tpl

@@ -0,0 +1,9 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{- else -}}
+{{- $cleanDoc := regexReplaceAllLiteral "(?s)<gateway:util:excludeFromCRD>.*?</gateway:util:excludeFromCRD>" $field.Doc "" -}}
+{{ markdownRenderFieldDoc $cleanDoc }}
+{{- end -}}
+{{- end -}}

hack/mkdocs/generate.sh

@@ -32,5 +32,13 @@ go install github.com/elastic/crd-ref-docs
 ${GOBIN}/crd-ref-docs \
     --source-path=${PWD}/apis \
     --config=crd-ref-docs.yaml \
+    --templates-dir=${PWD}/hack/crd-ref-templates/ \
     --renderer=markdown \
     --output-path=${PWD}/site-src/reference/spec.md
+
+${GOBIN}/crd-ref-docs \
+    --source-path=${PWD}/apisx \
+    --config=crd-ref-docs.yaml \
+    --templates-dir=${PWD}/hack/crd-ref-templates/ \
+    --renderer=markdown \
+    --output-path=${PWD}/site-src/reference/specx.md