feat: add api docs

.gitignore

@@ -25,3 +25,6 @@ go.work
 *.swp
 *.swo
 *~
+
+# macOS
+.DS_Store

Makefile

@@ -155,6 +155,17 @@ deploy: manifests kustomize ## Deploy controller to the K8s cluster specified in
 undeploy: kustomize ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
 	$(KUSTOMIZE) build config/default | $(KUBECTL) delete --ignore-not-found=$(ignore-not-found) -f -
 
+##@ Documentation
+
+.PHONY: api-docs
+api-docs: crd-ref-docs ## Generate api references docs.
+	$(CRD_REF_DOCS) \
+		--source-path=./api \
+		--renderer=markdown \
+		--output-path=./docs/api-references/docs.md \
+		--templates-dir=./docs/api-references/template/ \
+		--config=./docs/api-references/config.yaml
+
 ##@ Dependencies
 
 ## Location to install dependencies to
@@ -168,12 +179,14 @@ KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
 GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.5.0
 CONTROLLER_TOOLS_VERSION ?= v0.16.4
 ENVTEST_VERSION ?= release-0.19
 GOLANGCI_LINT_VERSION ?= v1.61.0
+CRD_REF_DOCS_VERSION ?= v0.1.0
 
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -190,6 +203,10 @@ envtest: $(ENVTEST) ## Download setup-envtest locally if necessary.
 $(ENVTEST): $(LOCALBIN)
 	$(call go-install-tool,$(ENVTEST),sigs.k8s.io/controller-runtime/tools/setup-envtest,$(ENVTEST_VERSION))
 
+.PHONY: crd-ref-docs
+crd-ref-docs: ## Install crd-ref-docs.
+	GOBIN=$(LOCALBIN) GO111MODULE=on go install github.com/elastic/crd-ref-docs@$(CRD_REF_DOCS_VERSION)
+
 .PHONY: golangci-lint
 golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)

docs/api-references/config.yaml

@@ -0,0 +1,11 @@
+processor:
+  ignoreGroupVersions:
+    - "GVK"
+  ignoreTypes:
+    - "Embedded[2-4]$"
+  ignoreFields:
+    - "status$"
+    - "TypeMeta$"
+  customMarkers:
+    - name: "hidefromdoc"
+      target: field

docs/api-references/docs.md

@@ -0,0 +1,72 @@
+# ETCD Operator API References
+
+## Packages
+- [operator.etcd.io/v1alpha1](#operatoretcdiov1alpha1)
+
+
+## operator.etcd.io/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group.
+
+### Resource Types
+- [EtcdCluster](#etcdcluster)
+- [EtcdClusterList](#etcdclusterlist)
+
+
+
+#### EtcdCluster
+
+
+
+EtcdCluster is the Schema for the etcdclusters API.
+
+
+
+_Appears in:_
+- [EtcdClusterList](#etcdclusterlist)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiVersion` _string_ | `operator.etcd.io/v1alpha1` | | |
+| `kind` _string_ | `EtcdCluster` | | |
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `spec` _[EtcdClusterSpec](#etcdclusterspec)_ |  |  |  |
+
+
+#### EtcdClusterList
+
+
+
+EtcdClusterList contains a list of EtcdCluster.
+
+
+
+
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiVersion` _string_ | `operator.etcd.io/v1alpha1` | | |
+| `kind` _string_ | `EtcdClusterList` | | |
+| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `items` _[EtcdCluster](#etcdcluster) array_ |  |  |  |
+
+
+#### EtcdClusterSpec
+
+
+
+EtcdClusterSpec defines the desired state of EtcdCluster.
+
+
+
+_Appears in:_
+- [EtcdCluster](#etcdcluster)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `size` _integer_ | Size is the expected size of the etcd cluster. |  |  |
+| `version` _string_ | Version is the expected version of the etcd container image. |  |  |
+
+
+
+

docs/api-references/template/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 -}}

docs/api-references/template/gv_list.tpl

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

docs/api-references/template/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 -}}

docs/api-references/template/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 -}}