feat: generate apidoc using genref (#228)

Closes #206

Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
Signed-off-by: Francesco Canovai <francesco.canovai@enterprisedb.com>
Co-authored-by: Francesco Canovai <francesco.canovai@enterprisedb.com>

.wordlist.txt

@@ -1,11 +1,21 @@
 Azurite
 BarmanObjectStore
+BarmanObjectStoreConfiguration
 BarmanObjectStores
 CloudNativePG
+EnvVar
 Gi
 IfNotPresent
+InstanceSidecarConfiguration
 MinIO
+ObjectMeta
+ObjectStore
+ObjectStoreSpec
+ObjectStoreStatus
 PITR
+RecoveryWindow
+RetentionPolicy
+ServerRecoveryWindow
 TLS
 TODO
 WAL
@@ -26,6 +36,7 @@ cnpg
 codebase
 csi
 customresourcedefinition
+devel
 externalClusters
 gcs
 gf
@@ -37,6 +48,7 @@ io
 isWALArchiver
 kubectl
 kubernetes
+md
 minio
 namespace
 namespaces
@@ -47,12 +59,15 @@ postgresql
 primaryUpdateStrategy
 rbac
 rc
+recoverability
 repos
+retentionCheckInterval
 rolebinding
 sc
 selfsigned
 serverName
 serviceaccount
+sig
 storageClass
 tfddg
 tgz

README.md

@@ -17,6 +17,7 @@ plugin for [CloudNativePG](https://cloudnative-pg.io/).
   - [Backup](#backup)
   - [Restore](#restore)
   - [Replica clusters](#replica-clusters)
+- [API Reference](#api-reference)
 
 ## Features
 
@@ -335,3 +336,8 @@ spec:
       parameters:
         barmanObjectName: minio-store-b
 ```
+
+## API Reference
+
+You can find the API reference on its
+[dedicated page](./docs/src/plugin-barman-cloud.v1.md).

Taskfile.yml

@@ -69,6 +69,22 @@ 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_APIDOC_SHA: ac27cc7677fc42ea129fd3c1aa2b2894aad3a246
+    cmds:
+      - GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/genref@${DAGGER_APIDOC_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
+      - ./docs/config.yaml
+    generates:
+      - ./docs/src/plugin-barman-cloud.v1.md
+
   go-test:
     desc: Run go test
     env:

api/v1/objectstore_types.go

@@ -48,6 +48,7 @@ type ObjectStoreSpec struct {
 	// +optional
 	RetentionPolicy string `json:"retentionPolicy,omitempty"`
 
+	// The configuration for the sidecar that runs in the instance pods
 	// +optional
 	InstanceSidecarConfiguration InstanceSidecarConfiguration `json:"instanceSidecarConfiguration,omitempty"`
 }
@@ -81,7 +82,12 @@ type ObjectStore struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata"`
 
+	// Specification of the desired behavior of the ObjectStore.
+	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 	Spec ObjectStoreSpec `json:"spec"`
+	// Most recently observed status of the ObjectStore. This data may not be up to
+	// date. Populated by the system. Read-only.
+	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 	// +optional
 	Status ObjectStoreStatus `json:"status,omitempty"`
 }

config/crd/bases/barmancloud.cnpg.io_objectstores.yaml

@@ -37,7 +37,9 @@ spec:
           metadata:
             type: object
           spec:
-            description: ObjectStoreSpec defines the desired state of ObjectStore.
+            description: |-
+              Specification of the desired behavior of the ObjectStore.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
             properties:
               configuration:
                 description: The configuration for the barman-cloud tool suite
@@ -381,8 +383,8 @@ spec:
                 - destinationPath
                 type: object
               instanceSidecarConfiguration:
-                description: InstanceSidecarConfiguration defines the configuration
+                description: The configuration for the sidecar that runs in the instance
-                  for the sidecar that runs in the instance pods.
+                  pods
                 properties:
                   env:
                     description: The environment to be explicitly passed to the sidecar
@@ -523,7 +525,10 @@ spec:
             - configuration
             type: object
           status:
-            description: ObjectStoreStatus defines the observed state of ObjectStore.
+            description: |-
+              Most recently observed status of the ObjectStore. This data may not be up to
+              date. Populated by the system. Read-only.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
             properties:
               serverRecoveryWindow:
                 additionalProperties:

docs/config.yaml

@@ -0,0 +1,24 @@
+hiddenMemberFields:
+  - "TypeMeta"
+
+externalPackages:
+  - 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/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

docs/markdown/members.tpl

@@ -0,0 +1,34 @@
+{{ define "members" }}
+  {{- /* . is a apiType */ -}}
+  {{- range .GetMembers -}}
+    {{- /* . is a apiMember */ -}}
+    {{- if not .Hidden }}
+<tr><td><code>{{ .FieldName }}</code>
+      {{- if and (not .IsOptional) (not .IsInline) }} <B>[Required]</B>{{- end -}}
+<br/>
+{{/* Link for type reference */}}
+      {{- with .GetType -}}
+        {{- if .Link -}}
+<a href="{{ .Link }}"><i>{{ .DisplayName }}</i></a>
+        {{- else -}}
+<i>{{ .DisplayName }}</i>
+        {{- end -}}
+      {{- end }}
+</td>
+<td>
+   {{- if .IsInline -}}
+(Members of <code>{{ .FieldName }}</code> are embedded into this type.)
+   {{- end }}
+   {{ if .GetComment -}}
+   {{ .GetComment }}
+   {{- else -}}
+   <span class="text-muted">No description provided.</span>
+   {{- end }}
+   {{- if and (eq (.GetType.Name.Name) "ObjectMeta") -}}
+Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.
+   {{- end -}}
+</td>
+</tr>
+    {{- end }}
+  {{- end }}
+{{ end }}

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

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 -}}
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+    {{- /* . is a apiType */ -}}
+    {{- if .IsExported -}}
+{{- /* Add apiVersion and kind rows if deemed necessary */}}
+<tr><td><code>apiVersion</code> <B>[Required]</B><br/>string</td><td><code>{{- .APIGroup -}}</code></td></tr>
+<tr><td><code>kind</code> <B>[Required]</B><br/>string</td><td><code>{{- .Name.Name -}}</code></td></tr>
+    {{- end -}}
+
+{{/* The actual list of members is in the following template */}}
+{{- template "members" . -}}
+</tbody>
+</table>
+{{- end -}}
+{{- end -}}

docs/src/plugin-barman-cloud.v1.md

@@ -0,0 +1,179 @@
+# API Reference
+
+<p>Package v1 contains API Schema definitions for the barmancloud v1 API group</p>
+
+
+## Resource Types
+
+
+- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore)
+
+## ObjectStore     {#barmancloud-cnpg-io-v1-ObjectStore}
+
+
+
+<p>ObjectStore is the Schema for the objectstores API.</p>
+
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><code>apiVersion</code> <B>[Required]</B><br/>string</td><td><code>barmancloud.cnpg.io/v1</code></td></tr>
+<tr><td><code>kind</code> <B>[Required]</B><br/>string</td><td><code>ObjectStore</code></td></tr>
+<tr><td><code>metadata</code> <B>[Required]</B><br/>
+<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta"><i>meta/v1.ObjectMeta</i></a>
+</td>
+<td>
+   <span class="text-muted">No description provided.</span>Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.</td>
+</tr>
+<tr><td><code>spec</code> <B>[Required]</B><br/>
+<a href="#barmancloud-cnpg-io-v1-ObjectStoreSpec"><i>ObjectStoreSpec</i></a>
+</td>
+<td>
+   <p>Specification of the desired behavior of the ObjectStore.
+More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status</p>
+</td>
+</tr>
+<tr><td><code>status</code><br/>
+<a href="#barmancloud-cnpg-io-v1-ObjectStoreStatus"><i>ObjectStoreStatus</i></a>
+</td>
+<td>
+   <p>Most recently observed status of the ObjectStore. This data may not be up to
+date. Populated by the system. Read-only.
+More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+## InstanceSidecarConfiguration     {#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration}
+
+
+**Appears in:**
+
+- [ObjectStoreSpec](#barmancloud-cnpg-io-v1-ObjectStoreSpec)
+
+
+<p>InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.</p>
+
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><code>env</code><br/>
+<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core"><i>[]core/v1.EnvVar</i></a>
+</td>
+<td>
+   <p>The environment to be explicitly passed to the sidecar</p>
+</td>
+</tr>
+<tr><td><code>retentionPolicyIntervalSeconds</code><br/>
+<i>int</i>
+</td>
+<td>
+   <p>The retentionCheckInterval defines the frequency at which the
+system checks and enforces retention policies.</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+## ObjectStoreSpec     {#barmancloud-cnpg-io-v1-ObjectStoreSpec}
+
+
+**Appears in:**
+
+- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore)
+
+
+<p>ObjectStoreSpec defines the desired state of ObjectStore.</p>
+
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><code>configuration</code> <B>[Required]</B><br/>
+<a href="https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api/#BarmanObjectStoreConfiguration"><i>github.com/cloudnative-pg/barman-cloud/pkg/api.BarmanObjectStoreConfiguration</i></a>
+</td>
+<td>
+   <p>The configuration for the barman-cloud tool suite</p>
+</td>
+</tr>
+<tr><td><code>retentionPolicy</code><br/>
+<i>string</i>
+</td>
+<td>
+   <p>RetentionPolicy is the retention policy to be used for backups
+and WALs (i.e. '60d'). The retention policy is expressed in the form
+of <code>XXu</code> where <code>XX</code> is a positive integer and <code>u</code> is in <code>[dwm]</code> -
+days, weeks, months.</p>
+</td>
+</tr>
+<tr><td><code>instanceSidecarConfiguration</code><br/>
+<a href="#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration"><i>InstanceSidecarConfiguration</i></a>
+</td>
+<td>
+   <p>The configuration for the sidecar that runs in the instance pods</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+## ObjectStoreStatus     {#barmancloud-cnpg-io-v1-ObjectStoreStatus}
+
+
+**Appears in:**
+
+- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore)
+
+
+<p>ObjectStoreStatus defines the observed state of ObjectStore.</p>
+
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><code>serverRecoveryWindow</code> <B>[Required]</B><br/>
+<a href="#barmancloud-cnpg-io-v1-RecoveryWindow"><i>map[string]RecoveryWindow</i></a>
+</td>
+<td>
+   <p>ServerRecoveryWindow maps each server to its recovery window</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+## RecoveryWindow     {#barmancloud-cnpg-io-v1-RecoveryWindow}
+
+
+**Appears in:**
+
+- [ObjectStoreStatus](#barmancloud-cnpg-io-v1-ObjectStoreStatus)
+
+
+<p>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.</p>
+
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><code>firstRecoverabilityPoint</code> <B>[Required]</B><br/>
+<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta"><i>meta/v1.Time</i></a>
+</td>
+<td>
+   <p>The first recoverability point in a PostgreSQL server refers to
+the earliest point in time to which the database can be
+restored.</p>
+</td>
+</tr>
+<tr><td><code>lastSuccussfulBackupTime</code> <B>[Required]</B><br/>
+<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta"><i>meta/v1.Time</i></a>
+</td>
+<td>
+   <p>The last successful backup time</p>
+</td>
+</tr>
+</tbody>
+</table>

manifest.yaml

@@ -36,7 +36,9 @@ spec:
           metadata:
             type: object
           spec:
-            description: ObjectStoreSpec defines the desired state of ObjectStore.
+            description: |-
+              Specification of the desired behavior of the ObjectStore.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
             properties:
               configuration:
                 description: The configuration for the barman-cloud tool suite
@@ -380,8 +382,8 @@ spec:
                 - destinationPath
                 type: object
               instanceSidecarConfiguration:
-                description: InstanceSidecarConfiguration defines the configuration
+                description: The configuration for the sidecar that runs in the instance
-                  for the sidecar that runs in the instance pods.
+                  pods
                 properties:
                   env:
                     description: The environment to be explicitly passed to the sidecar
@@ -522,7 +524,10 @@ spec:
             - configuration
             type: object
           status:
-            description: ObjectStoreStatus defines the observed state of ObjectStore.
+            description: |-
+              Most recently observed status of the ObjectStore. This data may not be up to
+              date. Populated by the system. Read-only.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
             properties:
               serverRecoveryWindow:
                 additionalProperties: