Add make target to automatically generate API docs.

Makefile

@@ -61,6 +61,15 @@ deploy-rbac:
 manifests: install-tools
 	controller-gen $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
 
+# Generate API reference documentation
+api-reference:
+	crd-ref-docs \
+		--source-path ./api/v1alpha1 \
+		--config ./docs/api/autogen/config.yaml \
+		--templates-dir ./docs/api/autogen/templates \
+		--output-path ./docs/api/rabbitmq.com.ref.asciidoc \
+		--max-depth 30
+
 # Run go fmt against code
 fmt:
 	go fmt ./...
@@ -69,8 +78,8 @@ fmt:
 vet:
 	go vet ./...
 
-# Generate code
-generate: install-tools
+# Generate code & docs
+generate: install-tools api-reference
 	controller-gen object:headerFile="hack/NOTICE.go.txt" paths="./..."
 
 check-env-docker-credentials: check-env-registry-server

docs/api/autogen/config.yaml

@@ -0,0 +1,2 @@
+render:
+  kubernetesVersion: "1.20"

docs/api/autogen/templates/gv_details.tpl

@@ -0,0 +1,20 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+[id="{{ asciidocGroupVersionID $gv | asciidocRenderAnchorID }}"]
+== {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+.Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | asciidocRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+=== Definitions
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

docs/api/autogen/templates/gv_list.tpl

@@ -0,0 +1,19 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+// Generated documentation. Please do not edit.
+:anchor_prefix: k8s-api
+
+[id="{p}-api-reference"]
+= API Reference
+
+.Packages
+{{- range $groupVersions }}
+- {{ asciidocRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

docs/api/autogen/templates/type.tpl

@@ -0,0 +1,35 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if asciidocShouldRenderType $type -}}
+
+[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"]
+==== {{ $type.Name  }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType  }}) {{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.References -}}
+.Appears In:
+****
+{{- range $type.SortedReferences }}
+- {{ asciidocRenderTypeLink . }}
+{{- end }}
+****
+{{- end }}
+
+{{ if $type.Members -}}
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+{{ if $type.GVK -}}
+| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
+| *`kind`* __string__ | `{{ $type.GVK.Kind }}`
+{{ end -}}
+
+{{ range $type.Members -}}
+| *`{{ .Name  }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }}
+{{ end -}}
+|===
+{{ end -}}
+
+{{- end -}}
+{{- end -}}

docs/api/autogen/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 -}}
+{{ $field.Doc }}
+{{- end -}}
+{{- end -}}

go.mod

@@ -3,6 +3,7 @@ module github.com/rabbitmq/messaging-topology-operator
 go 1.16
 
 require (
+	github.com/elastic/crd-ref-docs v0.0.7
 	github.com/go-logr/logr v0.4.0
 	github.com/michaelklishin/rabbit-hole/v2 v2.6.0
 	github.com/onsi/ginkgo v1.15.2

tools/tools.go

@@ -3,6 +3,7 @@
 package tools
 
 import (
+	_ "github.com/elastic/crd-ref-docs"
 	_ "github.com/onsi/ginkgo/ginkgo"
 	_ "sigs.k8s.io/controller-tools/cmd/controller-gen"
 	_ "sigs.k8s.io/kustomize/kustomize/v3"