Skip to content

Commit 4a2018e

Browse files
NiccoloFeimnencia
NiccoloFei
authored and
mnencia
committed
feat: generate apidoc using genref
Signed-off-by: Niccolò Fei <[email protected]>
1 parent 78fe21b commit 4a2018e

File tree

6 files changed

+348
-0
lines changed

6 files changed

+348
-0
lines changed

‎Taskfile.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,21 @@ tasks:
6969
sources:
7070
- ./**
7171

72+
apidoc:
73+
desc: Update the API Reference section of the documentation
74+
env:
75+
# renovate: datasource=git-refs depName=genref lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
76+
DAGGER_UNCOMMITTED_SHA: ac27cc7677fc42ea129fd3c1aa2b2894aad3a246
77+
cmds:
78+
- GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/genref@${DAGGER_UNCOMMITTED_SHA} genref --source .
79+
--args "-c=config.yaml" --args "-o=src" --args "-include=plugin-barman-cloud"
80+
file --path src/plugin-barman-cloud.v1.md
81+
export --path docs/src/plugin-barman-cloud.v1.md
82+
sources:
83+
- ./api/**/*.go
84+
generates:
85+
- ./docs/src/plugin-barman-cloud.v1.md
86+
7287
go-test:
7388
desc: Run go test
7489
env:

‎docs/config.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
hiddenMemberFields:
2+
- "TypeMeta"
3+
4+
externalPackages:
5+
- match: ^github\.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1\.RelabelConfig$
6+
target: https://pkg.go.dev/github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1#RelabelConfig
7+
- match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.Duration$
8+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration
9+
- match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.GroupVersionKind$
10+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GroupVersionKind
11+
- match: ^k8s\.io/apimachinery/pkg/apis/meta/v1\.GroupVersionResource$
12+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#GroupVersionResource
13+
- match: ^k8s\.io/apimachinery/pkg/types\.UID$
14+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID
15+
- match: ^k8s\.io/apimachinery/pkg/runtime\.RawExtension$
16+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension
17+
- match: ^k8s\.io/apimachinery/pkg/api/resource\.Quantity$
18+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity
19+
- match: ^k8s\.io/apimachinery/pkg/api/resource\.QuantityValue$
20+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue
21+
- match: ^k8s\.io/apimachinery/pkg/runtime\.Unknown$
22+
target: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown
23+
- match: ^time\.Duration$
24+
target: https://pkg.go.dev/time#Duration
25+
- match: ^k8s\.io/(api|apimachinery/pkg/apis)/
26+
target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}}
27+
- match: ^github\.com/cloudnative-pg/machinery
28+
target: https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api/#{{- .TypeIdentifier }}
29+
- match: ^github\.com/cloudnative-pg/barman-cloud
30+
target: https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api/#{{- .TypeIdentifier }}
31+
32+
hideTypePatterns:
33+
- "ParseError$"
34+
- "\\.ObjectStoreList$"
35+
36+
markdownDisabled: false
37+
38+
stripPrefix:
39+
- k8s.io/api/
40+
- k8s.io/apimachinery/pkg/apis/
41+
42+
apis:
43+
- name: plugin-barman-cloud
44+
title: API Reference
45+
package: github.com/cloudnative-pg/plugin-barman-cloud
46+
path: api/v1

‎docs/markdown/members.tpl‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{{ define "members" }}
2+
{{- /* . is a apiType */ -}}
3+
{{- range .GetMembers -}}
4+
{{- /* . is a apiMember */ -}}
5+
{{- if not .Hidden }}
6+
<tr><td><code>{{ .FieldName }}</code>
7+
{{- if and (not .IsOptional) (not .IsInline) }} <B>[Required]</B>{{- end -}}
8+
<br/>
9+
{{/* Link for type reference */}}
10+
{{- with .GetType -}}
11+
{{- if .Link -}}
12+
<a href="{{ .Link }}"><i>{{ .DisplayName }}</i></a>
13+
{{- else -}}
14+
<i>{{ .DisplayName }}</i>
15+
{{- end -}}
16+
{{- end }}
17+
</td>
18+
<td>
19+
{{- if .IsInline -}}
20+
(Members of <code>{{ .FieldName }}</code> are embedded into this type.)
21+
{{- end }}
22+
{{ if .GetComment -}}
23+
{{ .GetComment }}
24+
{{- else -}}
25+
<span class="text-muted">No description provided.</span>
26+
{{- end }}
27+
{{- if and (eq (.GetType.Name.Name) "ObjectMeta") -}}
28+
Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.
29+
{{- end -}}
30+
</td>
31+
</tr>
32+
{{- end }}
33+
{{- end }}
34+
{{ end }}

‎docs/markdown/pkg.tpl‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{{ define "packages" -}}
2+
3+
# API Reference
4+
5+
{{ $grpname := "" -}}
6+
{{- range $idx, $val := .packages -}}
7+
{{- if and (ne .GroupName "") (eq $grpname "") -}}
8+
{{ .GetComment -}}
9+
{{- $grpname = .GroupName -}}
10+
{{- end -}}
11+
{{- end }}
12+
13+
## Resource Types
14+
15+
{{ range .packages -}}
16+
{{- /* if ne .GroupName "" */ -}}
17+
{{- range .VisibleTypes -}}
18+
{{- if .IsExported }}
19+
- [{{ .DisplayName }}]({{ .Link }})
20+
{{- end -}}
21+
{{- end -}}
22+
{{- /* end */ -}}
23+
{{- end -}}
24+
25+
{{- range .packages -}}
26+
{{- if ne .GroupName "" -}}
27+
28+
{{- /* For package with a group name, list all type definitions in it. */ -}}
29+
{{- range .VisibleTypes -}}
30+
{{- if or .Referenced .IsExported -}}
31+
{{ template "type" . }}
32+
{{- end -}}
33+
{{- end }}
34+
{{- else -}}
35+
{{- /* For package w/o group name, list only types referenced. */ -}}
36+
{{- range .VisibleTypes -}}
37+
{{- if .Referenced -}}
38+
{{ template "type" . }}
39+
{{- end -}}
40+
{{- end }}
41+
{{- end }}
42+
{{- end }}
43+
{{- end }}

‎docs/markdown/type.tpl‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{{ define "type" }}
2+
3+
## {{ .Name.Name }} {#{{ .Anchor }}}
4+
5+
{{ if eq .Kind "Alias" -}}
6+
(Alias of `{{ .Underlying }}`)
7+
{{ end }}
8+
9+
{{- with .References }}
10+
**Appears in:**
11+
{{ range . }}
12+
{{ if or .Referenced .IsExported -}}
13+
- [{{ .DisplayName }}]({{ .Link }})
14+
{{ end -}}
15+
{{- end -}}
16+
{{- end }}
17+
18+
{{ if .GetComment -}}
19+
{{ .GetComment }}
20+
{{ end }}
21+
{{ if .GetMembers -}}
22+
<table class="table">
23+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
24+
<tbody>
25+
{{- /* . is a apiType */ -}}
26+
{{- if .IsExported -}}
27+
{{- /* Add apiVersion and kind rows if deemed necessary */}}
28+
<tr><td><code>apiVersion</code> <B>[Required]</B><br/>string</td><td><code>{{- .APIGroup -}}</code></td></tr>
29+
<tr><td><code>kind</code> <B>[Required]</B><br/>string</td><td><code>{{- .Name.Name -}}</code></td></tr>
30+
{{- end -}}
31+
32+
{{/* The actual list of members is in the following template */}}
33+
{{- template "members" . -}}
34+
</tbody>
35+
</table>
36+
{{- end -}}
37+
{{- end -}}

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

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# API Reference
2+
3+
<p>Package v1 contains API Schema definitions for the barmancloud v1 API group</p>
4+
5+
6+
## Resource Types
7+
8+
9+
- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore)
10+
11+
## ObjectStore {#barmancloud-cnpg-io-v1-ObjectStore}
12+
13+
14+
15+
<p>ObjectStore is the Schema for the objectstores API.</p>
16+
17+
18+
<table class="table">
19+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
20+
<tbody>
21+
<tr><td><code>apiVersion</code> <B>[Required]</B><br/>string</td><td><code>barmancloud.cnpg.io/v1</code></td></tr>
22+
<tr><td><code>kind</code> <B>[Required]</B><br/>string</td><td><code>ObjectStore</code></td></tr>
23+
<tr><td><code>metadata</code> <B>[Required]</B><br/>
24+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta"><i>meta/v1.ObjectMeta</i></a>
25+
</td>
26+
<td>
27+
<span class="text-muted">No description provided.</span>Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.</td>
28+
</tr>
29+
<tr><td><code>spec</code> <B>[Required]</B><br/>
30+
<a href="#barmancloud-cnpg-io-v1-ObjectStoreSpec"><i>ObjectStoreSpec</i></a>
31+
</td>
32+
<td>
33+
<span class="text-muted">No description provided.</span></td>
34+
</tr>
35+
<tr><td><code>status</code><br/>
36+
<a href="#barmancloud-cnpg-io-v1-ObjectStoreStatus"><i>ObjectStoreStatus</i></a>
37+
</td>
38+
<td>
39+
<span class="text-muted">No description provided.</span></td>
40+
</tr>
41+
</tbody>
42+
</table>
43+
44+
## InstanceSidecarConfiguration {#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration}
45+
46+
47+
**Appears in:**
48+
49+
- [ObjectStoreSpec](#barmancloud-cnpg-io-v1-ObjectStoreSpec)
50+
51+
52+
<p>InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.</p>
53+
54+
55+
<table class="table">
56+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
57+
<tbody>
58+
<tr><td><code>env</code><br/>
59+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core"><i>[]core/v1.EnvVar</i></a>
60+
</td>
61+
<td>
62+
<p>The environment to be explicitly passed to the sidecar</p>
63+
</td>
64+
</tr>
65+
<tr><td><code>retentionPolicyIntervalSeconds</code><br/>
66+
<i>int</i>
67+
</td>
68+
<td>
69+
<p>The retentionCheckInterval defines the frequency at which the
70+
system checks and enforces retention policies.</p>
71+
</td>
72+
</tr>
73+
</tbody>
74+
</table>
75+
76+
## ObjectStoreSpec {#barmancloud-cnpg-io-v1-ObjectStoreSpec}
77+
78+
79+
**Appears in:**
80+
81+
- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore)
82+
83+
84+
<p>ObjectStoreSpec defines the desired state of ObjectStore.</p>
85+
86+
87+
<table class="table">
88+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
89+
<tbody>
90+
<tr><td><code>configuration</code> <B>[Required]</B><br/>
91+
<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>
92+
</td>
93+
<td>
94+
<p>The configuration for the barman-cloud tool suite</p>
95+
</td>
96+
</tr>
97+
<tr><td><code>retentionPolicy</code><br/>
98+
<i>string</i>
99+
</td>
100+
<td>
101+
<p>RetentionPolicy is the retention policy to be used for backups
102+
and WALs (i.e. '60d'). The retention policy is expressed in the form
103+
of <code>XXu</code> where <code>XX</code> is a positive integer and <code>u</code> is in <code>[dwm]</code> -
104+
days, weeks, months.</p>
105+
</td>
106+
</tr>
107+
<tr><td><code>instanceSidecarConfiguration</code><br/>
108+
<a href="#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration"><i>InstanceSidecarConfiguration</i></a>
109+
</td>
110+
<td>
111+
<span class="text-muted">No description provided.</span></td>
112+
</tr>
113+
</tbody>
114+
</table>
115+
116+
## ObjectStoreStatus {#barmancloud-cnpg-io-v1-ObjectStoreStatus}
117+
118+
119+
**Appears in:**
120+
121+
- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore)
122+
123+
124+
<p>ObjectStoreStatus defines the observed state of ObjectStore.</p>
125+
126+
127+
<table class="table">
128+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
129+
<tbody>
130+
<tr><td><code>serverRecoveryWindow</code> <B>[Required]</B><br/>
131+
<a href="#barmancloud-cnpg-io-v1-RecoveryWindow"><i>map[string]RecoveryWindow</i></a>
132+
</td>
133+
<td>
134+
<p>ServerRecoveryWindow maps each server to its recovery window</p>
135+
</td>
136+
</tr>
137+
</tbody>
138+
</table>
139+
140+
## RecoveryWindow {#barmancloud-cnpg-io-v1-RecoveryWindow}
141+
142+
143+
**Appears in:**
144+
145+
- [ObjectStoreStatus](#barmancloud-cnpg-io-v1-ObjectStoreStatus)
146+
147+
148+
<p>RecoveryWindow represents the time span between the first
149+
recoverability point and the last successful backup of a PostgreSQL
150+
server, defining the period during which data can be restored.</p>
151+
152+
153+
<table class="table">
154+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
155+
<tbody>
156+
<tr><td><code>firstRecoverabilityPoint</code> <B>[Required]</B><br/>
157+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta"><i>meta/v1.Time</i></a>
158+
</td>
159+
<td>
160+
<p>The first recoverability point in a PostgreSQL server refers to
161+
the earliest point in time to which the database can be
162+
restored.</p>
163+
</td>
164+
</tr>
165+
<tr><td><code>lastSuccussfulBackupTime</code> <B>[Required]</B><br/>
166+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta"><i>meta/v1.Time</i></a>
167+
</td>
168+
<td>
169+
<p>The last successful backup time</p>
170+
</td>
171+
</tr>
172+
</tbody>
173+
</table>

0 commit comments

Comments
 (0)