From 95cfc7c6a829c8150f74ef991d2873659d5ff345 Mon Sep 17 00:00:00 2001 From: i325261 Date: Thu, 28 May 2026 14:14:49 +0200 Subject: [PATCH 1/3] Add CAPOperator API reference page Add includes/api-reference.html (generated from Go types via gen-crd-api-reference-docs) and content/en/docs/reference/_index.md that renders it via the include shortcode, matching the approach used in the cap-operator website. --- content/en/docs/reference/_index.md | 10 + includes/api-reference.html | 963 ++++++++++++++++++++++++++++ 2 files changed, 973 insertions(+) create mode 100644 content/en/docs/reference/_index.md create mode 100644 includes/api-reference.html diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md new file mode 100644 index 0000000..ea2b46e --- /dev/null +++ b/content/en/docs/reference/_index.md @@ -0,0 +1,10 @@ +--- +title: "Reference" +linkTitle: "Reference" +weight: 99 +type: "docs" +description: > + API reference +--- + +{{% include "includes/api-reference.html" %}} diff --git a/includes/api-reference.html b/includes/api-reference.html new file mode 100644 index 0000000..5deedec --- /dev/null +++ b/includes/api-reference.html @@ -0,0 +1,963 @@ +

Packages:

+ +

operator.sme.sap.com/v1alpha1

+
+

Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group

+
+Resource Types: + +

CAPOperator +

+
+

CAPOperator is the Schema for the CAPOperators API

+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +CAPOperatorSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+subscriptionServer
+ + +SubscriptionServer + + +		 +

SubscriptionServer specification

+
+dnsTarget
+ +string + +		 +

Public ingress URL for the cluster Load Balancer

+
+ingressGatewayLabels
+ + +[]NameValue + + +		 +

Labels used to identify the istio ingress-gateway component and its corresponding namespace. Usually {“app”:“istio-ingressgateway”,“istio”:“ingressgateway”}

+
+controller
+ + +Controller + + +		 +

Controller specification

+
+monitoring
+ + +Monitoring + + +		 +

Monitoring specification

+
+webhook
+ + +Webhook + + +		 +

Webhook specification

+
+
+status
+ + +CAPOperatorStatus + + +		 +
+

CAPOperatorSpec +

+

+(Appears on: CAPOperator) +

+
+

CAPOperatorSpec defines the desired state of CAPOperator

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+subscriptionServer
+ + +SubscriptionServer + + +		 +

SubscriptionServer specification

+
+dnsTarget
+ +string + +		 +

Public ingress URL for the cluster Load Balancer

+
+ingressGatewayLabels
+ + +[]NameValue + + +		 +

Labels used to identify the istio ingress-gateway component and its corresponding namespace. Usually {“app”:“istio-ingressgateway”,“istio”:“ingressgateway”}

+
+controller
+ + +Controller + + +		 +

Controller specification

+
+monitoring
+ + +Monitoring + + +		 +

Monitoring specification

+
+webhook
+ + +Webhook + + +		 +

Webhook specification

+
+

CAPOperatorStatus +

+

+(Appears on: CAPOperator) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+Status
+ +github.com/sap/component-operator-runtime/pkg/component.Status + +		 +

+(Members of Status are embedded into this type.) +

+

add other fields to status subresource here

+
+

CertManager +

+

+(Appears on: CertificateConfig) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+issuerName
+ +string + +		 +

Issuer name

+
+issuerKind
+ +string + +		 +

Issuer kind

+
+issuerGroup
+ +string + +		 +

Issuer group

+
+

CertificateConfig +

+

+(Appears on: SubscriptionServer, Webhook) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+gardener
+ + +Gardener + + +		 +

Gardener configuration

+
+certManager
+ + +CertManager + + +		 +

CertManager configuration

+
+

CertificateManager +(string alias)

+

+(Appears on: SubscriptionServer, Webhook) +

+
+

Supported values are Gardener, CertManager, or Default +For the subscription server, it can be either Gardener or CertManager, while for the webhook, it can be either Default or CertManager

+
+

CommonConfig +

+

+(Appears on: Controller, SubscriptionServer, Webhook) +

+
+

Common aspects for Controller, SubscriptionServer and Webhook

+
+ + + + + + + + + + + + + +
FieldDescription
+resources
+ + +Kubernetes core/v1.ResourceRequirements + + +		 +

Resource Requirements configuration

+
+

Controller +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+CommonConfig
+ + +CommonConfig + + +		 +

+(Members of CommonConfig are embedded into this type.) +

+
+detailedOperationalMetrics
+ +bool + +		 +

Optionally enable detailed opertational metrics for the controller by setting this to true

+
+maxConcurrentReconciles
+ + +MaxConcurrentReconciles + + +		 +

Configuration of maximum number of concurrent reconciles for the resources managed by the controller

+
+versionMonitoring
+ + +VersionMonitoring + + +		 +

Version monitoring configuration

+
+volumes
+ + +[]Kubernetes core/v1.Volume + + +		 +

Optionally specify list of additional volumes for the controller pod(s)

+
+volumeMounts
+ + +[]Kubernetes core/v1.VolumeMount + + +		 +

Optionally specify list of additional volumeMounts for the controller container(s)

+
+

Duration +(string alias)

+

+(Appears on: VersionMonitoring) +

+
+

Duration is a valid time duration that can be parsed by Prometheus +Supported units: y, w, d, h, m, s, ms +Examples: 30s, 1m, 1h20m15s, 15d

+
+

Gardener +

+

+(Appears on: CertificateConfig) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+issuerName
+ +string + +		 +

Issuer name

+
+issuerNamespace
+ +string + +		 +

Issuer namespace

+
+

Grafana +

+

+(Appears on: Monitoring) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+dashboard
+ + +GrafanaDashboard + + +		 +

Dashboard configuration

+
+

GrafanaDashboard +

+

+(Appears on: Grafana) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+configMapLabels
+ +map[string]string + +		 +

Labels for selecting ConfigMaps with dashboards in Grafana

+
+

MaxConcurrentReconciles +

+

+(Appears on: Controller) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+capApplication
+ +string + +		 +

Maximum number of concurrent reconciles for the cap application

+
+capApplicationVersion
+ +string + +		 +

Maximum number of concurrent reconciles for the cap application version

+
+capTenant
+ +string + +		 +

Maximum number of concurrent reconciles for the cap tenant

+
+capTenantOperation
+ +string + +		 +

Maximum number of concurrent reconciles for the cap tenant operation

+
+domain
+ +string + +		 +

Maximum number of concurrent reconciles for the domain

+
+clusterDomain
+ +string + +		 +

Maximum number of concurrent reconciles for the cluster domain

+
+

Monitoring +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+enabled
+ +bool + +		 +

Optionally enable Prometheus monitoring for all components

+
+serviceMonitorSelectorLabels
+ +map[string]string + +		 +

Prometheus service monitor selector labels

+
+grafana
+ + +Grafana + + +		 +

Grafana configuration

+
+

NameValue +

+

+(Appears on: CAPOperatorSpec) +

+
+

Generic Name/Value configuration

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+value
+ +string + +		 +
+

SubscriptionServer +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+CommonConfig
+ + +CommonConfig + + +		 +

+(Members of CommonConfig are embedded into this type.) +

+
+subDomain
+ +string + +		 +
+certificateManager
+ + +CertificateManager + + +		 +

Certificate manager which can be either Gardener or CertManager

+
+certificateConfig
+ + +CertificateConfig + + +		 +

Certificate configuration

+
+

VersionMonitoring +

+

+(Appears on: Controller) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+prometheusAddress
+ +string + +		 +

URL of the Prometheus server from which metrics related to managed application versions can be queried

+
+metricsEvaluationInterval
+ + +Duration + + +		 +

The duration (example 2h) after which versions are evaluated for deletion; based on specified workload metrics

+
+promClientAcquireRetryDelay
+ + +Duration + + +		 +

The duration (example 10m) to wait before retrying to acquire Prometheus client and verify connection, after a failed attempt

+
+

Webhook +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+CommonConfig
+ + +CommonConfig + + +		 +

+(Members of CommonConfig are embedded into this type.) +

+
+certificateManager
+ + +CertificateManager + + +		 +

Certificate manager which can be either Default or CertManager

+
+certificateConfig
+ + +CertificateConfig + + +		 +

Certificate configuration

+
+
+

+Generated with gen-crd-api-reference-docs +on git commit 13e5f09. +

From f7fdeeb183039790f8fb1bacb735e40eee3ab171 Mon Sep 17 00:00:00 2001 From: i325261 Date: Thu, 28 May 2026 14:35:32 +0200 Subject: [PATCH 2/3] Add API reference generation tooling Add Makefile with gen-api-docs target, hack/api-reference/ with config, templates, and generate.sh. The script extracts Go types from a given branch (default: main) into a temp dir and runs gen-crd-api-reference-docs to regenerate includes/api-reference.html. Usage: make gen-api-docs [BRANCH=] --- Makefile | 20 ++++++ hack/api-reference/config.json | 20 ++++++ hack/api-reference/generate.sh | 25 ++++++++ hack/api-reference/template/members.tpl | 48 +++++++++++++++ hack/api-reference/template/pkg.tpl | 49 +++++++++++++++ hack/api-reference/template/type.tpl | 81 +++++++++++++++++++++++++ includes/api-reference.html | 2 +- 7 files changed, 244 insertions(+), 1 deletion(-) create mode 100644 Makefile create mode 100644 hack/api-reference/config.json create mode 100755 hack/api-reference/generate.sh create mode 100644 hack/api-reference/template/members.tpl create mode 100644 hack/api-reference/template/pkg.tpl create mode 100644 hack/api-reference/template/type.tpl diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4ea6817 --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +LOCALBIN ?= $(shell pwd)/bin +API_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs +API_DOCS_VERSION ?= latest +BRANCH ?= main + +.PHONY: gen-api-docs +gen-api-docs: ## Generate API reference documentation from Go types. Override branch with BRANCH=. + bash hack/api-reference/generate.sh $(BRANCH) + +.PHONY: gen-crd-api-reference-docs +gen-crd-api-reference-docs: $(API_DOCS) ## Download gen-crd-api-reference-docs locally if necessary. +$(API_DOCS): $(LOCALBIN) + test -s $(LOCALBIN)/gen-crd-api-reference-docs || GOBIN=$(LOCALBIN) go install github.com/ahmetb/gen-crd-api-reference-docs@$(API_DOCS_VERSION) + +$(LOCALBIN): + mkdir -p $(LOCALBIN) + +.PHONY: help +help: ## Display this help. + @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST) diff --git a/hack/api-reference/config.json b/hack/api-reference/config.json new file mode 100644 index 0000000..9b853bd --- /dev/null +++ b/hack/api-reference/config.json @@ -0,0 +1,20 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://pkg.go.dev/{{.PackagePath}}#{{.TypeIdentifier}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/api-reference/generate.sh b/hack/api-reference/generate.sh new file mode 100755 index 0000000..d0cfee5 --- /dev/null +++ b/hack/api-reference/generate.sh @@ -0,0 +1,25 @@ +#!/bin/bash +# Generates includes/api-reference.html from the Go types on the given branch (default: main). +# Usage: ./generate.sh [branch] +# Run this from the repo root on the website branch. + +set -eo pipefail + +SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}") +REPO_ROOT=$(cd "$SCRIPT_DIR/../.." && pwd) +BRANCH=${1:-main} +TEMPDIR=$(mktemp -d) +trap 'rm -rf "$TEMPDIR"' EXIT + +echo "Extracting Go types from $BRANCH branch..." +git archive "$BRANCH" -- api/ go.mod go.sum | tar -x -C "$TEMPDIR" + +echo "Generating API reference..." +cd "$TEMPDIR" +"$REPO_ROOT/bin/gen-crd-api-reference-docs" \ + -config "$REPO_ROOT/hack/api-reference/config.json" \ + -template-dir "$REPO_ROOT/hack/api-reference/template" \ + -api-dir github.com/sap/cap-operator-lifecycle/api/v1alpha1 \ + -out-file "$REPO_ROOT/includes/api-reference.html" + +echo "Done: $REPO_ROOT/includes/api-reference.html" diff --git a/hack/api-reference/template/members.tpl b/hack/api-reference/template/members.tpl new file mode 100644 index 0000000..a529c67 --- /dev/null +++ b/hack/api-reference/template/members.tpl @@ -0,0 +1,48 @@ +{{ define "members" }} + +{{ range .Members }} +{{ if not (hiddenMember .)}} + + + {{ fieldName . }}
+ + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

+ (Members of {{ fieldName . }} are embedded into this type.) +

+ {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") }} +
+
+ + {{ template "members" .Type }} +
+ {{ end }} + + +{{ end }} +{{ end }} + +{{ end }} diff --git a/hack/api-reference/template/pkg.tpl b/hack/api-reference/template/pkg.tpl new file mode 100644 index 0000000..842ec93 --- /dev/null +++ b/hack/api-reference/template/pkg.tpl @@ -0,0 +1,49 @@ +{{ define "packages" }} + +{{ with .packages}} +

Packages:

+ +{{ end}} + +{{ range .packages }} +

+ {{- packageDisplayName . -}} +

+ + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} +
+ {{ safe (renderComments .) }} +
+ {{ end }} + {{ end }} + + Resource Types: +
    + {{- range (visibleTypes (sortedTypes .Types)) -}} + {{ if isExportedType . -}} +
  • + {{ typeDisplayName . }} +
    • + {{- end }} + {{- end -}} +
+ + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} +
+{{ end }} + +

+ Generated with gen-crd-api-reference-docs + {{ with .gitCommit }} on git commit {{ . }}{{end}}. +

+ +{{ end }} diff --git a/hack/api-reference/template/type.tpl b/hack/api-reference/template/type.tpl new file mode 100644 index 0000000..976e224 --- /dev/null +++ b/hack/api-reference/template/type.tpl @@ -0,0 +1,81 @@ +{{ define "type" }} + +

+ {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

+{{ with (typeReferences .) }} +

+ (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{- $prev = . -}} + {{ typeDisplayName . }} + {{- end -}} + ) +

+{{ end }} + +
+ {{ safe (renderComments .CommentLines) }} +
+ +{{ with (constantsOfType .) }} + + + + + + + + + {{- range . -}} + + {{- /* + renderComments implicitly creates a

element, so we + add one to the display name as well to make the contents + of the two cells align evenly. + */ -}} +

+ + + {{- end -}} + +
ValueDescription

{{ typeDisplayName . }}

{{ safe (renderComments .CommentLines) }}
+{{ end }} + +{{ if .Members }} + + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" .}} + +
FieldDescription
+ apiVersion
+ string		 + + {{apiGroup .}} + +
+ kind
+ string + 		{{.Name.Name}}
+{{ end }} + +{{ end }} diff --git a/includes/api-reference.html b/includes/api-reference.html index 5deedec..8fc69df 100644 --- a/includes/api-reference.html +++ b/includes/api-reference.html @@ -959,5 +959,5 @@

Webhook

Generated with gen-crd-api-reference-docs -on git commit 13e5f09. +.

From 0ee5190c26b13db748c88b28f7b5f261139bdbec Mon Sep 17 00:00:00 2001 From: i325261 Date: Wed, 3 Jun 2026 16:07:08 +0200 Subject: [PATCH 3/3] Refactor API documentation generation in Makefile and remove obsolete script --- Makefile | 39 +++++++++++++++++++--------------- hack/api-reference/generate.sh | 25 ---------------------- 2 files changed, 22 insertions(+), 42 deletions(-) delete mode 100755 hack/api-reference/generate.sh diff --git a/Makefile b/Makefile index 4ea6817..1075d04 100644 --- a/Makefile +++ b/Makefile @@ -1,20 +1,25 @@ -LOCALBIN ?= $(shell pwd)/bin -API_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs -API_DOCS_VERSION ?= latest -BRANCH ?= main +API_DOCS ?= $(CURDIR)/bin/gen-crd-api-reference-docs +BRANCH ?= $(shell git tag --sort=-version:refname | grep -v '^manager/' | grep -v '^helm/' | head -1) .PHONY: gen-api-docs -gen-api-docs: ## Generate API reference documentation from Go types. Override branch with BRANCH=. - bash hack/api-reference/generate.sh $(BRANCH) +gen-api-docs: $(API_DOCS) + @TEMPDIR=$$(mktemp -d) && \ + trap 'rm -rf "$$TEMPDIR"' EXIT && \ + echo "Extracting Go types from $(BRANCH)..." && \ + git archive $(BRANCH) -- api/ go.mod go.sum | tar -x -C "$$TEMPDIR" && \ + if [ ! -f "$$TEMPDIR/api/v1alpha1/doc.go" ]; then \ + git show main:api/v1alpha1/doc.go > "$$TEMPDIR/api/v1alpha1/doc.go"; \ + fi && \ + echo "Downloading dependencies..." && \ + cd "$$TEMPDIR" && \ + go mod download && \ + echo "Generating API reference..." && \ + $(API_DOCS) \ + -config $(CURDIR)/hack/api-reference/config.json \ + -template-dir $(CURDIR)/hack/api-reference/template \ + -api-dir ./api/v1alpha1 \ + -out-file $(CURDIR)/includes/api-reference.html && \ + echo "Done: $(CURDIR)/includes/api-reference.html" -.PHONY: gen-crd-api-reference-docs -gen-crd-api-reference-docs: $(API_DOCS) ## Download gen-crd-api-reference-docs locally if necessary. -$(API_DOCS): $(LOCALBIN) - test -s $(LOCALBIN)/gen-crd-api-reference-docs || GOBIN=$(LOCALBIN) go install github.com/ahmetb/gen-crd-api-reference-docs@$(API_DOCS_VERSION) - -$(LOCALBIN): - mkdir -p $(LOCALBIN) - -.PHONY: help -help: ## Display this help. - @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST) +$(API_DOCS): + GOBIN=$(CURDIR)/bin go install github.com/ahmetb/gen-crd-api-reference-docs@latest diff --git a/hack/api-reference/generate.sh b/hack/api-reference/generate.sh deleted file mode 100755 index d0cfee5..0000000 --- a/hack/api-reference/generate.sh +++ /dev/null @@ -1,25 +0,0 @@ -#!/bin/bash -# Generates includes/api-reference.html from the Go types on the given branch (default: main). -# Usage: ./generate.sh [branch] -# Run this from the repo root on the website branch. - -set -eo pipefail - -SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}") -REPO_ROOT=$(cd "$SCRIPT_DIR/../.." && pwd) -BRANCH=${1:-main} -TEMPDIR=$(mktemp -d) -trap 'rm -rf "$TEMPDIR"' EXIT - -echo "Extracting Go types from $BRANCH branch..." -git archive "$BRANCH" -- api/ go.mod go.sum | tar -x -C "$TEMPDIR" - -echo "Generating API reference..." -cd "$TEMPDIR" -"$REPO_ROOT/bin/gen-crd-api-reference-docs" \ - -config "$REPO_ROOT/hack/api-reference/config.json" \ - -template-dir "$REPO_ROOT/hack/api-reference/template" \ - -api-dir github.com/sap/cap-operator-lifecycle/api/v1alpha1 \ - -out-file "$REPO_ROOT/includes/api-reference.html" - -echo "Done: $REPO_ROOT/includes/api-reference.html"