diff --git a/Makefile b/Makefile index dd70137f7..8b7f7e486 100644 --- a/Makefile +++ b/Makefile @@ -78,7 +78,7 @@ help: ## Display this help. ##@ Generate: .PHONY: generate -generate: generate-manifests generate-code generate-mock +generate: generate-manifests generate-code generate-mock generate-api-docs .PHONY: generate-manifests generate-manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects. @@ -97,6 +97,14 @@ generate-mock: mockgen ## Generate mocks for the Linode API client. generate-flavors: $(KUSTOMIZE) bash hack/generate-flavors.sh +.PHONY: generate-api-docs +generate-api-docs: crd-ref-docs ## Generate API reference documentation. + $(CRD_REF_DOCS) \ + --config=./docs/.crd-ref-docs.yaml \ + --source-path=./api/ \ + --renderer=markdown \ + --output-path=./docs/src/reference + .PHONY: check-gen-diff check-gen-diff: git diff --no-ext-diff --exit-code @@ -301,6 +309,7 @@ KUBECTL ?= $(LOCALBIN)/kubectl KUSTOMIZE ?= $(LOCALBIN)/kustomize CTLPTL ?= $(LOCALBIN)/ctlptl CLUSTERCTL ?= $(LOCALBIN)/clusterctl +CRD_REF_DOCS ?= $(CACHE_BIN)/crd-ref-docs KUBEBUILDER ?= $(LOCALBIN)/kubebuilder CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen CONVERSION_GEN ?= $(CACHE_BIN)/conversion-gen @@ -313,12 +322,13 @@ NILAWAY ?= $(LOCALBIN)/nilaway GOVULNC ?= $(LOCALBIN)/govulncheck MOCKGEN ?= $(LOCALBIN)/mockgen GOWRAP ?= $(CACHE_BIN)/gowrap -S5CMD ?= $(CACHE_BIN)/s5cmd +S5CMD ?= $(CACHE_BIN)/s5cmd ## Tool Versions KUSTOMIZE_VERSION ?= v5.4.3 CTLPTL_VERSION ?= v0.8.29 CLUSTERCTL_VERSION ?= v1.7.2 +CRD_REF_DOCS_VERSION ?= v0.1.0 KUBECTL_VERSION ?= v1.28.0 KUBEBUILDER_VERSION ?= v3.15.1 CONTROLLER_TOOLS_VERSION ?= v0.16.5 @@ -355,6 +365,11 @@ $(CLUSTERCTL): $(LOCALBIN) curl -fsSL https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CLUSTERCTL_VERSION)/clusterctl-$(OS)-$(ARCH_SHORT) -o $(CLUSTERCTL) chmod +x $(CLUSTERCTL) +.PHONY: crd-ref-docs +crd-ref-docs: $(CRD_REF_DOCS) ## Download crd-ref-docs locally if necessary. +$(CRD_REF_DOCS): $(LOCALBIN) + GOBIN=$(CACHE_BIN) go install github.com/elastic/crd-ref-docs@$(CRD_REF_DOCS_VERSION) + .PHONY: kubectl kubectl: $(KUBECTL) ## Download kubectl locally if necessary. $(KUBECTL): $(LOCALBIN) diff --git a/docs/.crd-ref-docs.yaml b/docs/.crd-ref-docs.yaml new file mode 100644 index 000000000..e26109e01 --- /dev/null +++ b/docs/.crd-ref-docs.yaml @@ -0,0 +1,9 @@ +processor: + # RE2 regular expressions describing types that should be excluded from the generated documentation. + ignoreTypes: [] + # RE2 regular expressions describing type fields that should be excluded from the generated documentation. + ignoreFields: [] + +render: + # Version of Kubernetes to use when generating links to Kubernetes API documentation. + kubernetesVersion: '1.32' diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index fe13d997d..d5aef0968 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -33,4 +33,4 @@ - [Development](./developers/development.md) - [Releasing](./developers/releasing.md) - [Testing](./developers/testing.md) -- [Reference](./reference/reference.md) +- [Reference](./reference/out.md) diff --git a/docs/src/reference/reference.md b/docs/src/reference/reference.md deleted file mode 100644 index 774358341..000000000 --- a/docs/src/reference/reference.md +++ /dev/null @@ -1,4 +0,0 @@ -# Reference - -For reference documentation for CAPL API types, please refer to -the [godocs](https://pkg.go.dev/github.com/linode/cluster-api-provider-linode)