feat: Generate Build 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.

The main branch is used to generate the docs for now, since it contains
the necessary kubebuilder markers to generate useful reference
material. In the future, we can pin this to a release tag.

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 ?= "main"
+
+.PHONY: gen-api-docs
+gen-api-docs: crd-ref-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
+---