feat: Generate CRD docs (#197)

aenix-io · May 21, 2024 · 8db580c · 8db580c
1 parent d7a6f5a
commit 8db580c
Show file tree

Hide file tree

Showing 9 changed files with 358 additions and 3 deletions.
diff --git a/.crd-docs.yaml b/.crd-docs.yaml
@@ -0,0 +1,10 @@
+processor:
+  ignoreTypes:
+    - "(EtcdCluster)List$"
+    - "(EtcdCluster)Status$"
+  ignoreFields:
+    - "status$"
+    - "TypeMeta$"
+
+render:
+  kubernetesVersion: 1.30.1
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -6,7 +6,7 @@ repos:
   hooks:
     - id: trailing-whitespace
     - id: end-of-file-fixer
-      exclude: "^charts/etcd-operator/(values.schema.json|README.md)$"
+      exclude: "^charts/etcd-operator/(values.schema.json|README.md)|site/content/en/docs/v([.0-9]+)/reference/api.md$"
     - id: check-added-large-files
 - repo: local
   hooks:
@@ -24,6 +24,11 @@ repos:
       entry: sh -c "make lint-fix"
       language: system
       require_serial: true
+    - id: make-generate-docs
+      name: make-generate-docs
+      entry: sh -c "make generate-docs"
+      language: system
+      require_serial: true
     - id: make-mod-tidy
       name: make-mod-tidy
       entry: sh -c "make mod-tidy"

diff --git a/Makefile b/Makefile
@@ -55,6 +55,11 @@ manifests: controller-gen yq ## Generate WebhookConfiguration, ClusterRole and C
 generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
 	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
 
+.PHONY: generate-docs
+generate-docs: crd-ref-docs ## Generate CRD reference documentation.
+	@$(eval VERSION := $(shell $(YQ) '.params.version' site/hugo.yaml))
+	$(CRD_REF_DOCS) --config=.crd-docs.yaml --renderer=markdown --templates-dir="site/reference-templates" --output-path="site/content/en/docs/$(VERSION)/reference/api.md"
+
 .PHONY: fmt
 fmt: ## Run go fmt against code.
 	go fmt ./...
@@ -236,6 +241,7 @@ KIND ?= $(LOCALBIN)/kind
 HELM ?= $(LOCALBIN)/helm
 HELM_DOCS ?= $(LOCALBIN)/helm-docs
 YQ = $(LOCALBIN)/yq
+CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
 
 ## Tool Versions
 # renovate: datasource=github-tags depName=kubernetes-sigs/kustomize
@@ -276,6 +282,10 @@ controller-gen: $(LOCALBIN)
 envtest: $(LOCALBIN)
 	@test -x $(ENVTEST) || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@$(ENVTEST_VERSION)
 
+.PHONY: crd-ref-docs
+crd-ref-docs: $(LOCALBIN)
+	@test -x $(CRD_REF_DOCS) || GOBIN=$(LOCALBIN) go install github.com/elastic/crd-ref-docs@latest
+
 .PHONY: golangci-lint
 golangci-lint: $(LOCALBIN)
 	@test -x $(GOLANGCI_LINT) && $(GOLANGCI_LINT) version | grep -q $(GOLANGCI_LINT_VERSION) || \

diff --git a/site/content/en/docs/v0.2/reference/_index.md b/site/content/en/docs/v0.2/reference/_index.md
@@ -2,6 +2,5 @@
 title: Reference
 description: Low level reference docs for your project.
 weight: 9
+simple_list: true
 ---
-
-TODO
diff --git a/site/content/en/docs/v0.2/reference/api.md b/site/content/en/docs/v0.2/reference/api.md
@@ -0,0 +1,244 @@
+---
+title: API Reference
+description: Autogenerated API Reference for the CRD
+weight: 9
+simple_list: true
+---
+
+## Packages
+- [etcd.aenix.io/v1alpha1](#etcdaenixiov1alpha1)
+
+
+## etcd.aenix.io/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the etcd.aenix.io v1alpha1 API group
+
+### Resource Types
+- [EtcdCluster](#etcdcluster)
+
+
+
+#### EmbeddedMetadataResource
+
+
+
+
+
+
+
+_Appears in:_
+- [EtcdClusterSpec](#etcdclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metadata` _[EmbeddedObjectMetadata](#embeddedobjectmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+
+
+#### EmbeddedObjectMetadata
+
+
+
+EmbeddedObjectMetadata contains a subset of the fields included in k8s.io/apimachinery/pkg/apis/meta/v1.ObjectMeta
+Only fields which are relevant to embedded resources are included.
+
+
+
+_Appears in:_
+- [EmbeddedMetadataResource](#embeddedmetadataresource)
+- [EmbeddedPersistentVolumeClaim](#embeddedpersistentvolumeclaim)
+- [EmbeddedPodDisruptionBudget](#embeddedpoddisruptionbudget)
+- [EmbeddedService](#embeddedservice)
+- [PodTemplate](#podtemplate)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name must be unique within a namespace. Is required when creating resources, although<br />some resources may allow a client to request the generation of an appropriate name<br />automatically. Name is primarily intended for creation idempotence and configuration<br />definition.<br />Cannot be updated.<br />More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#names |  |  |
+| `labels` _object (keys:string, values:string)_ | Labels Map of string keys and values that can be used to organize and categorize<br />(scope and select) objects. May match selectors of replication controllers<br />and services.<br />More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels |  |  |
+| `annotations` _object (keys:string, values:string)_ | Annotations is an unstructured key value map stored with a resource that may be<br />set by external tools to store and retrieve arbitrary metadata. They are not<br />queryable and should be preserved when modifying objects.<br />More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations |  |  |
+
+
+#### EmbeddedPersistentVolumeClaim
+
+
+
+EmbeddedPersistentVolumeClaim is an embedded version of k8s.io/api/core/v1.PersistentVolumeClaim.
+It contains TypeMeta and a reduced ObjectMeta.
+
+
+
+_Appears in:_
+- [StorageSpec](#storagespec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metadata` _[EmbeddedObjectMetadata](#embeddedobjectmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `spec` _[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30.1/#persistentvolumeclaimspec-v1-core)_ | Spec defines the desired characteristics of a volume requested by a pod author.<br />More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims |  |  |
+
+
+#### EmbeddedPodDisruptionBudget
+
+
+
+EmbeddedPodDisruptionBudget describes PDB resource for etcd cluster members
+
+
+
+_Appears in:_
+- [EtcdClusterSpec](#etcdclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metadata` _[EmbeddedObjectMetadata](#embeddedobjectmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `spec` _[PodDisruptionBudgetSpec](#poddisruptionbudgetspec)_ | Spec defines the desired characteristics of a PDB.<br />More info: https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#pod-disruption-budgets |  |  |
+
+
+#### EmbeddedService
+
+
+
+
+
+
+
+_Appears in:_
+- [EtcdClusterSpec](#etcdclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metadata` _[EmbeddedObjectMetadata](#embeddedobjectmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `spec` _[ServiceSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30.1/#servicespec-v1-core)_ | Spec defines the behavior of the service. |  |  |
+
+
+#### EtcdCluster
+
+
+
+EtcdCluster is the Schema for the etcdclusters API
+
+
+
+
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiVersion` _string_ | `etcd.aenix.io/v1alpha1` | | |
+| `kind` _string_ | `EtcdCluster` | | |
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30.1/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `spec` _[EtcdClusterSpec](#etcdclusterspec)_ |  |  |  |
+
+
+#### EtcdClusterSpec
+
+
+
+EtcdClusterSpec defines the desired state of EtcdCluster
+
+
+
+_Appears in:_
+- [EtcdCluster](#etcdcluster)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `replicas` _integer_ | Replicas is the count of etcd instances in cluster. | 3 | Minimum: 0 <br /> |
+| `options` _object (keys:string, values:string)_ | Options are the extra arguments to pass to the etcd container. |  |  |
+| `podTemplate` _[PodTemplate](#podtemplate)_ | PodTemplate defines the desired state of PodSpec for etcd members. If not specified, default values will be used. |  |  |
+| `serviceTemplate` _[EmbeddedService](#embeddedservice)_ | Service defines the desired state of Service for etcd members. If not specified, default values will be used. |  |  |
+| `headlessServiceTemplate` _[EmbeddedMetadataResource](#embeddedmetadataresource)_ | HeadlessService defines the desired state of HeadlessService for etcd members. If not specified, default values will be used. |  |  |
+| `podDisruptionBudgetTemplate` _[EmbeddedPodDisruptionBudget](#embeddedpoddisruptionbudget)_ | PodDisruptionBudgetTemplate describes PDB resource to create for etcd cluster members. Nil to disable. |  |  |
+| `storage` _[StorageSpec](#storagespec)_ |  |  |  |
+| `security` _[SecuritySpec](#securityspec)_ | Security describes security settings of etcd (authentication, certificates, rbac) |  |  |
+
+
+
+
+
+
+#### PodDisruptionBudgetSpec
+
+
+
+
+
+
+
+_Appears in:_
+- [EmbeddedPodDisruptionBudget](#embeddedpoddisruptionbudget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `minAvailable` _[IntOrString](#intorstring)_ | MinAvailable describes minimum ready replicas. If both are empty, controller will implicitly<br />calculate MaxUnavailable based on number of replicas<br />Mutually exclusive with MaxUnavailable. |  |  |
+| `maxUnavailable` _[IntOrString](#intorstring)_ | MinAvailable describes maximum not ready replicas. If both are empty, controller will implicitly<br />calculate MaxUnavailable based on number of replicas<br />Mutually exclusive with MinAvailable |  |  |
+
+
+#### PodTemplate
+
+
+
+PodTemplate allows overrides, such as sidecars, init containers, changes to the security context, etc to the pod template generated by the operator.
+
+
+
+_Appears in:_
+- [EtcdClusterSpec](#etcdclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metadata` _[EmbeddedObjectMetadata](#embeddedobjectmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
+| `spec` _[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30.1/#podspec-v1-core)_ | Spec follows the structure of a regular Pod spec. Overrides defined here will be strategically merged with the default pod spec, generated by the operator. |  |  |
+
+
+#### SecuritySpec
+
+
+
+SecuritySpec defines security settings for etcd.
+
+
+
+_Appears in:_
+- [EtcdClusterSpec](#etcdclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `tls` _[TLSSpec](#tlsspec)_ | Section for user-managed tls certificates |  |  |
+
+
+#### StorageSpec
+
+
+
+StorageSpec defines the configured storage for a etcd members.
+If neither `emptyDir` nor `volumeClaimTemplate` is specified, then by default an [EmptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) will be used.
+
+
+
+_Appears in:_
+- [EtcdClusterSpec](#etcdclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `emptyDir` _[EmptyDirVolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30.1/#emptydirvolumesource-v1-core)_ | EmptyDirVolumeSource to be used by the StatefulSets. If specified, used in place of any volumeClaimTemplate. More<br />info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir |  |  |
+| `volumeClaimTemplate` _[EmbeddedPersistentVolumeClaim](#embeddedpersistentvolumeclaim)_ | A PVC spec to be used by the StatefulSets. |  |  |
+
+
+#### TLSSpec
+
+
+
+TLSSpec defines user-managed certificates names.
+
+
+
+_Appears in:_
+- [SecuritySpec](#securityspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `peerTrustedCASecret` _string_ | Trusted CA certificate secret to secure peer-to-peer communication between etcd nodes. It is expected to have tls.crt field in the secret. |  |  |
+| `peerSecret` _string_ | Certificate secret to secure peer-to-peer communication between etcd nodes. It is expected to have tls.crt and tls.key fields in the secret. |  |  |
+| `serverSecret` _string_ | Server certificate secret to secure client-server communication. Is provided to the client who connects to etcd by client port (2379 by default).<br />It is expected to have tls.crt and tls.key fields in the secret. |  |  |
+| `clientTrustedCASecret` _string_ | Trusted CA for client certificates that are provided by client to etcd. It is expected to have tls.crt field in the secret. |  |  |
+| `clientSecret` _string_ | Client certificate for etcd-operator to do maintenance. It is expected to have tls.crt and tls.key fields in the secret. |  |  |
+
+
diff --git a/site/reference-templates/gv_detail.tpl b/site/reference-templates/gv_detail.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 -}}
diff --git a/site/reference-templates/gv_list.tpl b/site/reference-templates/gv_list.tpl
@@ -0,0 +1,20 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+---
+title: API Reference
+description: Autogenerated API Reference for the CRD
+weight: 9
+simple_list: true
+---
+
+## Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}
diff --git a/site/reference-templates/type.tpl b/site/reference-templates/type.tpl
@@ -0,0 +1,40 @@
+{{- 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 -}} {{ . }} <br />{{ end }} |
+{{ end -}}
+
+{{ end -}}
+
+{{- end -}}
+{{- end -}}