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

Signed-off-by: Todd Short <tshort@redhat.com>

Author: tmshort

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
 
 
 

hack/tools/quick-helm/main.go

@@ -0,0 +1,67 @@
+package main
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"text/template"
+
+	"gopkg.in/yaml.v2"
+)
+
+// 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: |-