Skip to content

Commit 43bb319

Browse files
committed
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 <[email protected]>
1 parent f17f3c5 commit 43bb319

17 files changed

+109
-8
lines changed

Makefile

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -524,11 +524,14 @@ quickstart: manifests #EXHELP Generate the unified installation release manifest
524524
.PHONY: crd-ref-docs
525525
API_REFERENCE_FILENAME := olmv1-api-reference.md
526526
API_REFERENCE_DIR := $(ROOT_DIR)/docs/api-reference
527+
API_REF_TMP := $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME).tmp
527528
crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents.
528529
rm -f $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME)
529530
$(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api/ \
530531
--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
531-
--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME);
532+
--renderer=markdown --output-path=$(API_REF_TMP)
533+
go run hack/tools/quick-helm/main.go -values helm/olmv1/values.yaml $(API_REF_TMP) > $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME)
534+
rm $(API_REF_TMP)
532535

533536
VENVDIR := $(abspath docs/.venv)
534537

api/v1/clustercatalog_types.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ const (
5353

5454
// ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster.
5555
// For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
56+
// Please see ClusterCatalog documentation located at {{ .Values.docs.clusterCatalogURL }}
5657
type ClusterCatalog struct {
5758
metav1.TypeMeta `json:",inline"`
5859

api/v1/clusterextension_types.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -527,6 +527,7 @@ type ClusterExtensionInstallStatus struct {
527527
// +kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp`
528528

529529
// ClusterExtension is the Schema for the clusterextensions API
530+
// Please see ClusterExtension documentation located at {{ .Values.docs.clusterExtensionURL }}
530531
type ClusterExtension struct {
531532
metav1.TypeMeta `json:",inline"`
532533
metav1.ObjectMeta `json:"metadata,omitempty"`

api/v1/clusterextensionrevision_types.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,7 @@ type ClusterExtensionRevisionStatus struct {
214214
// at a time. Ownership of objects is transitioned from one revision to the next as the extension is upgraded
215215
// or reconfigured. Once the latest revision has rolled out successfully, previous active revisions are archived for
216216
// posterity.
217+
// Please see ClusterExtensionRevision documentation located at {{ .Values.docs.clusterExtensionRevisionURL }}
217218
type ClusterExtensionRevision struct {
218219
metav1.TypeMeta `json:",inline"`
219220
metav1.ObjectMeta `json:"metadata,omitempty"`

docs/api-reference/olmv1-api-reference.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@ _Appears in:_
127127

128128
ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster.
129129
For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
130+
Please see ClusterCatalog documentation located at https://www.example.com/ClusterCatalog
130131

131132

132133

@@ -222,6 +223,7 @@ _Appears in:_
222223

223224

224225
ClusterExtension is the Schema for the clusterextensions API
226+
Please see ClusterExtension documentation located at https://www.example.com/ClusterExtension
225227

226228

227229

go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ require (
3232
golang.org/x/mod v0.30.0
3333
golang.org/x/sync v0.18.0
3434
golang.org/x/tools v0.39.0
35+
gopkg.in/yaml.v2 v2.4.0
3536
helm.sh/helm/v3 v3.19.2
3637
k8s.io/api v0.34.1
3738
k8s.io/apiextensions-apiserver v0.34.1
@@ -241,7 +242,6 @@ require (
241242
gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
242243
gopkg.in/inf.v0 v0.9.1 // indirect
243244
gopkg.in/warnings.v0 v0.1.2 // indirect
244-
gopkg.in/yaml.v2 v2.4.0 // indirect
245245
gopkg.in/yaml.v3 v3.0.1 // indirect
246246
k8s.io/controller-manager v0.33.2 // indirect
247247
k8s.io/kubectl v0.34.0 // indirect

hack/tools/quick-helm/main.go

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
package main
2+
3+
import (
4+
"bytes"
5+
"flag"
6+
"fmt"
7+
"io"
8+
"log"
9+
"os"
10+
"text/template"
11+
12+
"gopkg.in/yaml.v2"
13+
)
14+
15+
// Reads templated documents and does templating based on the inValues, dumps to stdout
16+
func executeTemplate(inValues io.Reader, templates ...string) error {
17+
tpl, err := template.ParseFiles(templates...)
18+
if err != nil {
19+
return fmt.Errorf("error parsing template(s): %v", err)
20+
}
21+
22+
buf := bytes.NewBuffer(nil)
23+
_, err = io.Copy(buf, inValues)
24+
if err != nil {
25+
return fmt.Errorf("failed to read values: %v", err)
26+
}
27+
28+
var values map[string]interface{}
29+
err = yaml.Unmarshal(buf.Bytes(), &values)
30+
if err != nil {
31+
return fmt.Errorf("failed to parse values: %v", err)
32+
}
33+
34+
// Add the .Values to the values that are read, to make it more helm-like
35+
topvalues := map[string]interface{}{
36+
"Values": values,
37+
}
38+
err = tpl.Execute(os.Stdout, topvalues)
39+
if err != nil {
40+
return fmt.Errorf("failed to execute template: %v", err)
41+
}
42+
return nil
43+
}
44+
45+
func main() {
46+
valuesFile := flag.String("values", "", "Path to values YAML file (required)")
47+
flag.Parse()
48+
49+
if *valuesFile == "" {
50+
log.Println("Error: --values flag is required")
51+
flag.Usage()
52+
os.Exit(1)
53+
}
54+
55+
valuesReader, err := os.Open(*valuesFile)
56+
if err != nil {
57+
log.Printf("Failed to open values file: %v\n", err)
58+
os.Exit(1)
59+
}
60+
defer valuesReader.Close()
61+
62+
err = executeTemplate(valuesReader, flag.Args()...)
63+
if err != nil {
64+
log.Println(err)
65+
os.Exit(1)
66+
}
67+
}

helm/olmv1/base/catalogd/crd/experimental/olm.operatorframework.io_clustercatalogs.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ spec:
3131
description: |-
3232
ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster.
3333
For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
34+
Please see ClusterCatalog documentation located at {{ .Values.docs.clusterCatalogURL }}
3435
properties:
3536
apiVersion:
3637
description: |-

helm/olmv1/base/catalogd/crd/standard/olm.operatorframework.io_clustercatalogs.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ spec:
3131
description: |-
3232
ClusterCatalog enables users to make File-Based Catalog (FBC) catalog data available to the cluster.
3333
For more information on FBC, see https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs
34+
Please see ClusterCatalog documentation located at {{ .Values.docs.clusterCatalogURL }}
3435
properties:
3536
apiVersion:
3637
description: |-

helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ spec:
3535
at a time. Ownership of objects is transitioned from one revision to the next as the extension is upgraded
3636
or reconfigured. Once the latest revision has rolled out successfully, previous active revisions are archived for
3737
posterity.
38+
Please see ClusterExtensionRevision documentation located at {{ .Values.docs.clusterExtensionRevisionURL }}
3839
properties:
3940
apiVersion:
4041
description: |-

0 commit comments

Comments
 (0)