From c75a680f6ca0c22e002a1006e42a0d4f0ecc913c Mon Sep 17 00:00:00 2001 From: Sergey Shevchenko Date: Wed, 24 Apr 2024 20:46:36 +0300 Subject: [PATCH] feat: Generate CRD docs --- .crd-docs.yaml | 10 + .pre-commit-config.yaml | 7 +- Makefile | 10 + site/content/en/docs/v0.2/reference/_index.md | 3 +- site/content/en/docs/v0.2/reference/api.md | 244 ++++++++++++++++++ site/reference-templates/gv_detail.tpl | 19 ++ site/reference-templates/gv_list.tpl | 20 ++ site/reference-templates/type.tpl | 40 +++ site/reference-templates/type_members.tpl | 8 + 9 files changed, 358 insertions(+), 3 deletions(-) create mode 100644 .crd-docs.yaml create mode 100644 site/content/en/docs/v0.2/reference/api.md create mode 100644 site/reference-templates/gv_detail.tpl create mode 100644 site/reference-templates/gv_list.tpl create mode 100644 site/reference-templates/type.tpl create mode 100644 site/reference-templates/type_members.tpl diff --git a/.crd-docs.yaml b/.crd-docs.yaml new file mode 100644 index 00000000..b4de85e8 --- /dev/null +++ b/.crd-docs.yaml @@ -0,0 +1,10 @@ +processor: + ignoreTypes: + - "(EtcdCluster)List$" + - "(EtcdCluster)Status$" + ignoreFields: + - "status$" + - "TypeMeta$" + +render: + kubernetesVersion: 1.29 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a612aa6f..e8203552 100644 --- 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 index cf7106e3..57999295 100644 --- 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 index 99acc582..faacee21 100644 --- 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 new file mode 100644 index 00000000..bad6e11f --- /dev/null +++ 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
some resources may allow a client to request the generation of an appropriate name
automatically. Name is primarily intended for creation idempotence and configuration
definition.
Cannot be updated.
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
(scope and select) objects. May match selectors of replication controllers
and services.
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
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
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.29/#persistentvolumeclaimspec-v1-core)_ | Spec defines the desired characteristics of a volume requested by a pod author.
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.
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.29/#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.29/#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
| +| `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
calculate MaxUnavailable based on number of replicas
Mutually exclusive with MaxUnavailable. | | | +| `maxUnavailable` _[IntOrString](#intorstring)_ | MinAvailable describes maximum not ready replicas. If both are empty, controller will implicitly
calculate MaxUnavailable based on number of replicas
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.29/#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.29/#emptydirvolumesource-v1-core)_ | EmptyDirVolumeSource to be used by the StatefulSets. If specified, used in place of any volumeClaimTemplate. More
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).
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 new file mode 100644 index 00000000..30ad0d75 --- /dev/null +++ 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 new file mode 100644 index 00000000..e39be9b0 --- /dev/null +++ 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 new file mode 100644 index 00000000..405a32af --- /dev/null +++ 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 -}} {{ . }}
{{ end }} | +{{ end -}} + +{{ end -}} + +{{- end -}} +{{- end -}} diff --git a/site/reference-templates/type_members.tpl b/site/reference-templates/type_members.tpl new file mode 100644 index 00000000..041758a8 --- /dev/null +++ b/site/reference-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 -}} +{{ markdownRenderFieldDoc $field.Doc }} +{{- end -}} +{{- end -}}