feat: generate apidoc using genref (#228)

NiccoloFei · fcanovai · web-flow · commit 74bdb9a590f1 · 2025-03-27T22:42:46.000+01:00
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>
diff --git a/.wordlist.txt b/.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
diff --git a/README.md b/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).
diff --git a/Taskfile.yml b/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:
diff --git a/api/v1/objectstore_types.go b/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"`
 }
diff --git a/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml b/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
-                  for the sidecar that runs in the instance pods.
+                description: The configuration for the sidecar that runs in the instance
+                  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:
diff --git a/docs/config.yaml b/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
diff --git a/docs/markdown/members.tpl b/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 }}
diff --git a/docs/markdown/pkg.tpl 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
@@ -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 -}}
diff --git a/docs/src/plugin-barman-cloud.v1.md b/docs/src/plugin-barman-cloud.v1.md
diff --git a/manifest.yaml b/manifest.yaml
