From d62ffba8fb6e0eb084d8921275f28af669ba07b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niccol=C3=B2=20Fei?= Date: Mon, 24 Mar 2025 14:13:16 +0100 Subject: [PATCH] feat: generate apidoc using genref MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Niccolò Fei --- Taskfile.yml | 15 +++ docs/config.yaml | 46 ++++++++ docs/markdown/members.tpl | 34 ++++++ docs/markdown/pkg.tpl | 43 +++++++ docs/markdown/type.tpl | 37 ++++++ docs/src/plugin-barman-cloud.v1.md | 173 +++++++++++++++++++++++++++++ 6 files changed, 348 insertions(+) create mode 100644 docs/config.yaml create mode 100644 docs/markdown/members.tpl create mode 100644 docs/markdown/pkg.tpl create mode 100644 docs/markdown/type.tpl create mode 100644 docs/src/plugin-barman-cloud.v1.md diff --git a/Taskfile.yml b/Taskfile.yml index 35f1fc0..b2d979e 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -69,6 +69,21 @@ tasks: sources: - ./** + apidoc: + desc: Update the API Reference section of the documentation + env: + # renovate: datasource=git-refs depName=genref lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main + DAGGER_UNCOMMITTED_SHA: ac27cc7677fc42ea129fd3c1aa2b2894aad3a246 + cmds: + - GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/genref@${DAGGER_UNCOMMITTED_SHA} genref --source . + --args "-c=config.yaml" --args "-o=src" --args "-include=plugin-barman-cloud" + file --path src/plugin-barman-cloud.v1.md + export --path docs/src/plugin-barman-cloud.v1.md + sources: + - ./api/**/*.go + generates: + - ./docs/src/plugin-barman-cloud.v1.md + go-test: desc: Run go test env: diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 0000000..ee0c1a9 --- /dev/null +++ b/docs/config.yaml @@ -0,0 +1,46 @@ +hiddenMemberFields: + - "TypeMeta" + +externalPackages: + - match: ^github\.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1\.RelabelConfig$ + target: https://pkg.go.dev/github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1#RelabelConfig + - match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.Duration$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration + - match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.GroupVersionKind$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GroupVersionKind + - match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.GroupVersionResource$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GroupVersionResource + - match: ^k8s\.io/apimachinery/pkg/types\.UID$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID + - match: ^k8s\.io/apimachinery/pkg/runtime\.RawExtension$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension + - match: ^k8s\.io/apimachinery/pkg/api/resource\.Quantity$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity + - match: ^k8s\.io/apimachinery/pkg/api/resource\.QuantityValue$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue + - match: ^k8s\.io/apimachinery/pkg/runtime\.Unknown$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown + - match: ^time\.Duration$ + target: https://pkg.go.dev/time#Duration + - match: ^k8s\.io/(api|apimachinery/pkg/apis)/ + target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}} + - match: ^github\.com/cloudnative-pg/machinery + target: https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api/#{{- .TypeIdentifier }} + - match: ^github\.com/cloudnative-pg/barman-cloud + target: https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api/#{{- .TypeIdentifier }} + +hideTypePatterns: + - "ParseError$" + - "\\.ObjectStoreList$" + +markdownDisabled: false + +stripPrefix: + - k8s.io/api/ + - k8s.io/apimachinery/pkg/apis/ + +apis: + - name: plugin-barman-cloud + title: API Reference + package: github.com/cloudnative-pg/plugin-barman-cloud + path: api/v1 diff --git a/docs/markdown/members.tpl b/docs/markdown/members.tpl new file mode 100644 index 0000000..d3bacd1 --- /dev/null +++ b/docs/markdown/members.tpl @@ -0,0 +1,34 @@ +{{ define "members" }} + {{- /* . is a apiType */ -}} + {{- range .GetMembers -}} + {{- /* . is a apiMember */ -}} + {{- if not .Hidden }} +{{ .FieldName }} + {{- if and (not .IsOptional) (not .IsInline) }} [Required]{{- end -}} +
+{{/* Link for type reference */}} + {{- with .GetType -}} + {{- if .Link -}} +{{ .DisplayName }} + {{- else -}} +{{ .DisplayName }} + {{- end -}} + {{- end }} + + + {{- if .IsInline -}} +(Members of {{ .FieldName }} are embedded into this type.) + {{- end }} + {{ if .GetComment -}} + {{ .GetComment }} + {{- else -}} + No description provided. + {{- end }} + {{- if and (eq (.GetType.Name.Name) "ObjectMeta") -}} +Refer to the Kubernetes API documentation for the fields of the metadata field. + {{- end -}} + + + {{- end }} + {{- end }} +{{ end }} diff --git a/docs/markdown/pkg.tpl b/docs/markdown/pkg.tpl new file mode 100644 index 0000000..345d032 --- /dev/null +++ b/docs/markdown/pkg.tpl @@ -0,0 +1,43 @@ +{{ define "packages" -}} + +# API Reference + +{{ $grpname := "" -}} +{{- range $idx, $val := .packages -}} + {{- if and (ne .GroupName "") (eq $grpname "") -}} +{{ .GetComment -}} +{{- $grpname = .GroupName -}} + {{- end -}} +{{- end }} + +## Resource Types + +{{ range .packages -}} + {{- /* if ne .GroupName "" */ -}} + {{- range .VisibleTypes -}} + {{- if .IsExported }} +- [{{ .DisplayName }}]({{ .Link }}) + {{- end -}} + {{- end -}} + {{- /* end */ -}} +{{- end -}} + +{{- range .packages -}} + {{- if ne .GroupName "" -}} + + {{- /* For package with a group name, list all type definitions in it. */ -}} + {{- range .VisibleTypes -}} + {{- if or .Referenced .IsExported -}} +{{ template "type" . }} + {{- end -}} + {{- end }} + {{- else -}} + {{- /* For package w/o group name, list only types referenced. */ -}} + {{- range .VisibleTypes -}} + {{- if .Referenced -}} +{{ template "type" . }} + {{- end -}} + {{- end }} + {{- end }} +{{- end }} +{{- end }} diff --git a/docs/markdown/type.tpl b/docs/markdown/type.tpl new file mode 100644 index 0000000..91f7621 --- /dev/null +++ b/docs/markdown/type.tpl @@ -0,0 +1,37 @@ +{{ define "type" }} + +## {{ .Name.Name }} {#{{ .Anchor }}} + +{{ if eq .Kind "Alias" -}} +(Alias of `{{ .Underlying }}`) +{{ end }} + +{{- with .References }} +**Appears in:** +{{ range . }} +{{ if or .Referenced .IsExported -}} +- [{{ .DisplayName }}]({{ .Link }}) +{{ end -}} +{{- end -}} +{{- end }} + +{{ if .GetComment -}} +{{ .GetComment }} +{{ end }} +{{ if .GetMembers -}} + + + + {{- /* . is a apiType */ -}} + {{- if .IsExported -}} +{{- /* Add apiVersion and kind rows if deemed necessary */}} + + + {{- end -}} + +{{/* The actual list of members is in the following template */}} +{{- template "members" . -}} + +
FieldDescription
apiVersion [Required]
string		{{- .APIGroup -}}
kind [Required]
string		{{- .Name.Name -}}
+{{- end -}} +{{- end -}} diff --git a/docs/src/plugin-barman-cloud.v1.md b/docs/src/plugin-barman-cloud.v1.md new file mode 100644 index 0000000..58b1fc3 --- /dev/null +++ b/docs/src/plugin-barman-cloud.v1.md @@ -0,0 +1,173 @@ +# API Reference + +

Package v1 contains API Schema definitions for the barmancloud v1 API group

+ + +## Resource Types + + +- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) + +## ObjectStore {#barmancloud-cnpg-io-v1-ObjectStore} + + + +

ObjectStore is the Schema for the objectstores API.

+ + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		barmancloud.cnpg.io/v1
kind [Required]
string		ObjectStore
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+ObjectStoreSpec +		 + No description provided.
status
+ObjectStoreStatus +		 + No description provided.
+ +## InstanceSidecarConfiguration {#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration} + + +**Appears in:** + +- [ObjectStoreSpec](#barmancloud-cnpg-io-v1-ObjectStoreSpec) + + +

InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.

+ + + + + + + + + + + + +
FieldDescription
env
+[]core/v1.EnvVar +		 +

The environment to be explicitly passed to the sidecar

+
retentionPolicyIntervalSeconds
+int +		 +

The retentionCheckInterval defines the frequency at which the +system checks and enforces retention policies.

+
+ +## ObjectStoreSpec {#barmancloud-cnpg-io-v1-ObjectStoreSpec} + + +**Appears in:** + +- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) + + +

ObjectStoreSpec defines the desired state of ObjectStore.

+ + + + + + + + + + + + + + + +
FieldDescription
configuration [Required]
+github.com/cloudnative-pg/barman-cloud/pkg/api.BarmanObjectStoreConfiguration +		 +

The configuration for the barman-cloud tool suite

+
retentionPolicy
+string +		 +

RetentionPolicy is the retention policy to be used for backups +and WALs (i.e. '60d'). The retention policy is expressed in the form +of XXu where XX is a positive integer and u is in [dwm] - +days, weeks, months.

+
instanceSidecarConfiguration
+InstanceSidecarConfiguration +		 + No description provided.
+ +## ObjectStoreStatus {#barmancloud-cnpg-io-v1-ObjectStoreStatus} + + +**Appears in:** + +- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) + + +

ObjectStoreStatus defines the observed state of ObjectStore.

+ + + + + + + + + +
FieldDescription
serverRecoveryWindow [Required]
+map[string]RecoveryWindow +		 +

ServerRecoveryWindow maps each server to its recovery window

+
+ +## RecoveryWindow {#barmancloud-cnpg-io-v1-RecoveryWindow} + + +**Appears in:** + +- [ObjectStoreStatus](#barmancloud-cnpg-io-v1-ObjectStoreStatus) + + +

RecoveryWindow represents the time span between the first +recoverability point and the last successful backup of a PostgreSQL +server, defining the period during which data can be restored.

+ + + + + + + + + + + + +
FieldDescription
firstRecoverabilityPoint [Required]
+meta/v1.Time +		 +

The first recoverability point in a PostgreSQL server refers to +the earliest point in time to which the database can be +restored.

+
lastSuccussfulBackupTime [Required]
+meta/v1.Time +		 +

The last successful backup time

+
\ No newline at end of file