📖 WIP: OPRUN-4357: Add documentation URLs into CRD descriptions

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)
 

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"`
 

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"`

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"`

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
 
 
 

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

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)
+	}
+}

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: |-

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: |-

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: |-

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: |-

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: |-

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

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: |-

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: |-

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: |-

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: |-