mirror of
https://github.com/cloudnative-pg/plugin-barman-cloud.git
synced 2026-01-12 05:33:11 +01:00
feat: generate apidoc using genref
Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
This commit is contained in:
Niccolò Fei
Francesco Canovai
parent
e1f00919d3
commit
d62ffba8fb
15
Taskfile.yml
15
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:
|
||||
|
||||
46
docs/config.yaml
Normal file
46
docs/config.yaml
Normal file
@ -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
|
||||
34
docs/markdown/members.tpl
Normal file
34
docs/markdown/members.tpl
Normal file
@ -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 }}
|
||||
43
docs/markdown/pkg.tpl
Normal file
43
docs/markdown/pkg.tpl
Normal file
@ -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 }}
|
||||
37
docs/markdown/type.tpl
Normal file
37
docs/markdown/type.tpl
Normal file
@ -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 -}}
|
||||
173
docs/src/plugin-barman-cloud.v1.md
Normal file
173
docs/src/plugin-barman-cloud.v1.md
Normal file
@ -0,0 +1,173 @@
|
||||
# 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>
|
||||
<span class="text-muted">No description provided.</span></td>
|
||||
</tr>
|
||||
<tr><td><code>status</code><br/>
|
||||
<a href="#barmancloud-cnpg-io-v1-ObjectStoreStatus"><i>ObjectStoreStatus</i></a>
|
||||
</td>
|
||||
<td>
|
||||
<span class="text-muted">No description provided.</span></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>
|
||||
<span class="text-muted">No description provided.</span></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>
|
||||
Loading…
Reference in New Issue
Block a user