From 0dece5b01f875e8d2d03b80c6d370c58f99b2b7f Mon Sep 17 00:00:00 2001 From: Todd Short Date: Tue, 9 Dec 2025 10:40:37 -0500 Subject: [PATCH] Add documentation URLs into CRD descriptions These documentation URLs are templated, so that they can be updated downstream as needed. Added **quick-helm** utility to go template a file using helm-like semantics (i.e. everything is prefixed with `.Values`) This is used to update the docs/api-reference/olmv1-api-reference.md file, otherwise, Go templates are left in the file. Signed-off-by: Todd Short --- Makefile | 5 +- api/v1/clustercatalog_types.go | 1 + api/v1/clusterextension_types.go | 1 + api/v1/clusterextensionrevision_types.go | 1 + docs/api-reference/olmv1-api-reference.md | 2 + go.mod | 2 +- hack/tools/quick-helm/main.go | 67 +++++++++++++++++++ ....operatorframework.io_clustercatalogs.yaml | 1 + ....operatorframework.io_clustercatalogs.yaml | 1 + ...ramework.io_clusterextensionrevisions.yaml | 1 + ...peratorframework.io_clusterextensions.yaml | 4 +- ...peratorframework.io_clusterextensions.yaml | 4 +- helm/olmv1/values.yaml | 5 ++ manifests/experimental-e2e.yaml | 6 +- manifests/experimental.yaml | 6 +- manifests/standard-e2e.yaml | 5 +- manifests/standard.yaml | 5 +- 17 files changed, 109 insertions(+), 8 deletions(-) create mode 100644 hack/tools/quick-helm/main.go diff --git a/Makefile b/Makefile index c7d9ea5cfe..9819a8c4a2 100644 --- a/Makefile +++ b/Makefile @@ -524,11 +524,14 @@ quickstart: manifests #EXHELP Generate the unified installation release manifest .PHONY: crd-ref-docs API_REFERENCE_FILENAME := olmv1-api-reference.md API_REFERENCE_DIR := $(ROOT_DIR)/docs/api-reference +API_REF_TMP := $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME).tmp crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents. rm -f $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME) $(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api/ \ --config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \ - --renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME); + --renderer=markdown --output-path=$(API_REF_TMP) + go run hack/tools/quick-helm/main.go -values helm/olmv1/values.yaml $(API_REF_TMP) > $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME) + rm $(API_REF_TMP) VENVDIR := $(abspath docs/.venv) diff --git a/api/v1/clustercatalog_types.go b/api/v1/clustercatalog_types.go index c18fa3c7e6..11ed7eda8c 100644 --- a/api/v1/clustercatalog_types.go +++ b/api/v1/clustercatalog_types.go @@ -53,6 +53,7 @@ const ( // ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. // For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs +// Please see ClusterCatalog documentation located at {{ .Values.docs.clusterCatalogURL }} type ClusterCatalog struct { metav1.TypeMeta `json:",inline"` diff --git a/api/v1/clusterextension_types.go b/api/v1/clusterextension_types.go index 2a19fc98f3..2213205b42 100644 --- a/api/v1/clusterextension_types.go +++ b/api/v1/clusterextension_types.go @@ -527,6 +527,7 @@ type ClusterExtensionInstallStatus struct { // +kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp` // ClusterExtension is the Schema for the clusterextensions API +// Please see ClusterExtension documentation located at {{ .Values.docs.clusterExtensionURL }} type ClusterExtension struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` diff --git a/api/v1/clusterextensionrevision_types.go b/api/v1/clusterextensionrevision_types.go index 368a8fca88..3c30bdece1 100644 --- a/api/v1/clusterextensionrevision_types.go +++ b/api/v1/clusterextensionrevision_types.go @@ -214,6 +214,7 @@ type ClusterExtensionRevisionStatus struct { // at a time. Ownership of objects is transitioned from one revision to the next as the extension is upgraded // or reconfigured. Once the latest revision has rolled out successfully, previous active revisions are archived for // posterity. +// Please see ClusterExtensionRevision documentation located at {{ .Values.docs.clusterExtensionRevisionURL }} type ClusterExtensionRevision struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` diff --git a/docs/api-reference/olmv1-api-reference.md b/docs/api-reference/olmv1-api-reference.md index 54f95eca29..d9dde83491 100644 --- a/docs/api-reference/olmv1-api-reference.md +++ b/docs/api-reference/olmv1-api-reference.md @@ -127,6 +127,7 @@ _Appears in:_ ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs +Please see ClusterCatalog documentation located at https://www.example.com/ClusterCatalog @@ -222,6 +223,7 @@ _Appears in:_ ClusterExtension is the Schema for the clusterextensions API +Please see ClusterExtension documentation located at https://www.example.com/ClusterExtension diff --git a/go.mod b/go.mod index b94dd33696..ba5d1971ee 100644 --- a/go.mod +++ b/go.mod @@ -32,6 +32,7 @@ require ( golang.org/x/mod v0.30.0 golang.org/x/sync v0.18.0 golang.org/x/tools v0.39.0 + gopkg.in/yaml.v3 v3.0.1 helm.sh/helm/v3 v3.19.2 k8s.io/api v0.34.1 k8s.io/apiextensions-apiserver v0.34.1 @@ -242,7 +243,6 @@ require ( gopkg.in/inf.v0 v0.9.1 // indirect gopkg.in/warnings.v0 v0.1.2 // indirect gopkg.in/yaml.v2 v2.4.0 // indirect - gopkg.in/yaml.v3 v3.0.1 // indirect k8s.io/controller-manager v0.33.2 // indirect k8s.io/kubectl v0.34.0 // indirect oras.land/oras-go/v2 v2.6.0 // indirect diff --git a/hack/tools/quick-helm/main.go b/hack/tools/quick-helm/main.go new file mode 100644 index 0000000000..b80d189192 --- /dev/null +++ b/hack/tools/quick-helm/main.go @@ -0,0 +1,67 @@ +package main + +import ( + "bytes" + "flag" + "fmt" + "io" + "log" + "os" + "text/template" + + "gopkg.in/yaml.v3" +) + +// Reads templated documents and does templating based on the inValues, dumps to stdout +func executeTemplate(inValues io.Reader, templates ...string) error { + tpl, err := template.ParseFiles(templates...) + if err != nil { + return fmt.Errorf("error parsing template(s): %v", err) + } + + buf := bytes.NewBuffer(nil) + _, err = io.Copy(buf, inValues) + if err != nil { + return fmt.Errorf("failed to read values: %v", err) + } + + var values map[string]interface{} + err = yaml.Unmarshal(buf.Bytes(), &values) + if err != nil { + return fmt.Errorf("failed to parse values: %v", err) + } + + // Add the .Values to the values that are read, to make it more helm-like + topvalues := map[string]interface{}{ + "Values": values, + } + err = tpl.Execute(os.Stdout, topvalues) + if err != nil { + return fmt.Errorf("failed to execute template: %v", err) + } + return nil +} + +func main() { + valuesFile := flag.String("values", "", "Path to values YAML file (required)") + flag.Parse() + + if *valuesFile == "" { + log.Println("Error: --values flag is required") + flag.Usage() + os.Exit(1) + } + + valuesReader, err := os.Open(*valuesFile) + if err != nil { + log.Printf("Failed to open values file: %v\n", err) + os.Exit(1) + } + defer valuesReader.Close() + + err = executeTemplate(valuesReader, flag.Args()...) + if err != nil { + log.Println(err) + os.Exit(1) + } +} diff --git a/helm/olmv1/base/catalogd/crd/experimental/olm.operatorframework.io_clustercatalogs.yaml b/helm/olmv1/base/catalogd/crd/experimental/olm.operatorframework.io_clustercatalogs.yaml index c78a57b925..1036fb9298 100644 --- a/helm/olmv1/base/catalogd/crd/experimental/olm.operatorframework.io_clustercatalogs.yaml +++ b/helm/olmv1/base/catalogd/crd/experimental/olm.operatorframework.io_clustercatalogs.yaml @@ -31,6 +31,7 @@ spec: description: |- ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs + Please see ClusterCatalog documentation located at {{ .Values.docs.clusterCatalogURL }} properties: apiVersion: description: |- diff --git a/helm/olmv1/base/catalogd/crd/standard/olm.operatorframework.io_clustercatalogs.yaml b/helm/olmv1/base/catalogd/crd/standard/olm.operatorframework.io_clustercatalogs.yaml index 94f1d7121d..e8d1cb0702 100644 --- a/helm/olmv1/base/catalogd/crd/standard/olm.operatorframework.io_clustercatalogs.yaml +++ b/helm/olmv1/base/catalogd/crd/standard/olm.operatorframework.io_clustercatalogs.yaml @@ -31,6 +31,7 @@ spec: description: |- ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs + Please see ClusterCatalog documentation located at {{ .Values.docs.clusterCatalogURL }} properties: apiVersion: description: |- diff --git a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml index c448a4da46..455a4cdd4c 100644 --- a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml +++ b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml @@ -35,6 +35,7 @@ spec: at a time. Ownership of objects is transitioned from one revision to the next as the extension is upgraded or reconfigured. Once the latest revision has rolled out successfully, previous active revisions are archived for posterity. + Please see ClusterExtensionRevision documentation located at {{ .Values.docs.clusterExtensionRevisionURL }} properties: apiVersion: description: |- diff --git a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml index a6738cbe38..86fd95326e 100644 --- a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml +++ b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml @@ -34,7 +34,9 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtension is the Schema for the clusterextensions API + description: |- + ClusterExtension is the Schema for the clusterextensions API + Please see ClusterExtension documentation located at {{ .Values.docs.clusterExtensionURL }} properties: apiVersion: description: |- diff --git a/helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml b/helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml index a0983e41f9..a5cde3964a 100644 --- a/helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml +++ b/helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml @@ -34,7 +34,9 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtension is the Schema for the clusterextensions API + description: |- + ClusterExtension is the Schema for the clusterextensions API + Please see ClusterExtension documentation located at {{ .Values.docs.clusterExtensionURL }} properties: apiVersion: description: |- diff --git a/helm/olmv1/values.yaml b/helm/olmv1/values.yaml index cb454f6250..9f78a3e8b9 100644 --- a/helm/olmv1/values.yaml +++ b/helm/olmv1/values.yaml @@ -96,3 +96,8 @@ deployments: - ALL readOnlyRootFilesystem: true terminationMessagePolicy: FallbackToLogsOnError +# Documentation URLs +docs: + clusterExtensionURL: https://www.example.com/ClusterExtension + clusterExtensionRevisionURL: https://www.example.com/ClusterExtensionRevision + clusterCatalogURL: https://www.example.com/ClusterCatalog diff --git a/manifests/experimental-e2e.yaml b/manifests/experimental-e2e.yaml index 47a36152c5..666bf2dcf8 100644 --- a/manifests/experimental-e2e.yaml +++ b/manifests/experimental-e2e.yaml @@ -213,6 +213,7 @@ spec: description: |- ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs + Please see ClusterCatalog documentation located at https://www.example.com/ClusterCatalog properties: apiVersion: description: |- @@ -660,6 +661,7 @@ spec: at a time. Ownership of objects is transitioned from one revision to the next as the extension is upgraded or reconfigured. Once the latest revision has rolled out successfully, previous active revisions are archived for posterity. + Please see ClusterExtensionRevision documentation located at https://www.example.com/ClusterExtensionRevision properties: apiVersion: description: |- @@ -934,7 +936,9 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtension is the Schema for the clusterextensions API + description: |- + ClusterExtension is the Schema for the clusterextensions API + Please see ClusterExtension documentation located at https://www.example.com/ClusterExtension properties: apiVersion: description: |- diff --git a/manifests/experimental.yaml b/manifests/experimental.yaml index a6b68fc0a4..c13f9b9da5 100644 --- a/manifests/experimental.yaml +++ b/manifests/experimental.yaml @@ -178,6 +178,7 @@ spec: description: |- ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs + Please see ClusterCatalog documentation located at https://www.example.com/ClusterCatalog properties: apiVersion: description: |- @@ -625,6 +626,7 @@ spec: at a time. Ownership of objects is transitioned from one revision to the next as the extension is upgraded or reconfigured. Once the latest revision has rolled out successfully, previous active revisions are archived for posterity. + Please see ClusterExtensionRevision documentation located at https://www.example.com/ClusterExtensionRevision properties: apiVersion: description: |- @@ -899,7 +901,9 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtension is the Schema for the clusterextensions API + description: |- + ClusterExtension is the Schema for the clusterextensions API + Please see ClusterExtension documentation located at https://www.example.com/ClusterExtension properties: apiVersion: description: |- diff --git a/manifests/standard-e2e.yaml b/manifests/standard-e2e.yaml index 1aed38ba96..62e10ea9bf 100644 --- a/manifests/standard-e2e.yaml +++ b/manifests/standard-e2e.yaml @@ -213,6 +213,7 @@ spec: description: |- ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs + Please see ClusterCatalog documentation located at https://www.example.com/ClusterCatalog properties: apiVersion: description: |- @@ -659,7 +660,9 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtension is the Schema for the clusterextensions API + description: |- + ClusterExtension is the Schema for the clusterextensions API + Please see ClusterExtension documentation located at https://www.example.com/ClusterExtension properties: apiVersion: description: |- diff --git a/manifests/standard.yaml b/manifests/standard.yaml index 34cc579181..a1ac88d489 100644 --- a/manifests/standard.yaml +++ b/manifests/standard.yaml @@ -178,6 +178,7 @@ spec: description: |- ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster. For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs + Please see ClusterCatalog documentation located at https://www.example.com/ClusterCatalog properties: apiVersion: description: |- @@ -624,7 +625,9 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtension is the Schema for the clusterextensions API + description: |- + ClusterExtension is the Schema for the clusterextensions API + Please see ClusterExtension documentation located at https://www.example.com/ClusterExtension properties: apiVersion: description: |-