feat: Generate API Reference Docs

Auto-generate API reference docs from Go comments. This is considered
best practice.

- Utilize elastic/crd-ref-docs tool. This is much easier to use than
  the Kubernetes CRD docs stack.
- Copy markdown templates from elastic/crd-ref-docs, so they can be
  customized later.
- Use Makefile to run script generating docs from Shipwright build
  project.

Signed-off-by: Adam Kaplan <[email protected]>

.gitignore

@@ -6,5 +6,11 @@ resources/
 public/
 .hugo_build.lock
 
+# Supporting tools
+bin/
+
+# API Generation
+api-gen/build/
+
 # IDEs
 .vscode

Makefile

@@ -37,4 +37,19 @@ serve: ## serve the content locally for testing
 
 .PHONY: serve-preview
 serve-preview: ## serve the preview content locally for testing
-	hugo -t docsy server -F
+	hugo -t docsy server -F
+
+.PHONY: bin-dir
+bin-dir: ## Creates a local "bin" directory for helper applications.
+	@mkdir ./bin || true
+
+.PHONY: crd-ref-docs
+crd-ref-docs: bin-dir ## install crd-ref-docs tool
+	GOBIN=$(shell pwd)/bin go install github.com/elastic/[email protected]
+
+BUILD_REPO ?= "https://github.com/shipwright-io/build.git"
+BUILD_VERSION ?= "v0.14.0"
+
+.PHONY: gen-api-docs
+gen-api-docs: ## generate API reference documentation
+	BUILD_REPO=$(BUILD_REPO) BUILD_VERSION=$(BUILD_VERSION) ./hack/gen-api-docs.sh

api-gen/build.yaml

@@ -0,0 +1,5 @@
+processor:
+  ignoreFields:
+    - "TypeMeta$"
+render:
+  kubernetesVersion: 1.30

api-gen/templates/markdown/gv_details.tpl

@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+# {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if len $gv.Kinds  }}
+## Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

api-gen/templates/markdown/gv_list.tpl

@@ -0,0 +1,18 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+---
+title: {{env "API_GROUP"}} Resources
+weight: {{env "API_WEIGHT"}}
+---
+
+# Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

api-gen/templates/markdown/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  }}` _{{ 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 -}}

api-gen/templates/markdown/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 -}}

content/en/docs/ref/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Reference"
+weight: 30
+---
+
+This section contains reference documentation.

content/en/docs/ref/api/_index.md

@@ -0,0 +1,4 @@
+---
+title: API Reference
+weight: 10
+---