From c37047029d01d0edb670d8b7d3fc5b008392060b Mon Sep 17 00:00:00 2001 From: Francesco Canovai Date: Thu, 17 Apr 2025 13:19:35 +0100 Subject: [PATCH] docs: generate pure markdown documentation (#251) Switch to building documentation in markdown, avoiding the markdown+html hybrid we have. Closes #250 Signed-off-by: Francesco Canovai --- Taskfile.yml | 21 ++- api/v1/groupversion_info.go | 3 - docs/config.yaml | 42 +++--- docs/markdown/gv_details.tpl | 19 +++ docs/markdown/gv_list.tpl | 15 +++ docs/markdown/members.tpl | 34 ----- docs/markdown/pkg.tpl | 43 ------ docs/markdown/type.tpl | 70 +++++----- docs/markdown/type_members.tpl | 8 ++ docs/src/plugin-barman-cloud.v1.md | 201 +++++++++-------------------- renovate.json5 | 16 ++- 11 files changed, 195 insertions(+), 277 deletions(-) create mode 100644 docs/markdown/gv_details.tpl create mode 100644 docs/markdown/gv_list.tpl delete mode 100644 docs/markdown/members.tpl delete mode 100644 docs/markdown/pkg.tpl create mode 100644 docs/markdown/type_members.tpl diff --git a/Taskfile.yml b/Taskfile.yml index 8469ad3..ff36d39 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -58,6 +58,7 @@ tasks: desc: Check for uncommitted changes deps: - manifest-main + - apidoc env: # renovate: datasource=git-refs depName=uncommitted lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main DAGGER_UNCOMMITTED_SHA: db65290569cb7723a32e72fcfb134668e7b998c8 @@ -68,17 +69,26 @@ tasks: apidoc: desc: Update the API Reference section of the documentation + deps: + - controller-gen env: - # renovate: datasource=git-refs depName=genref lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main - DAGGER_APIDOC_SHA: db65290569cb7723a32e72fcfb134668e7b998c8 + # renovate: datasource=git-refs depName=crd-gen-refs lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main + DAGGER_CRDGENREF_SHA: ba865842d907910c469d016c3ecfa009e4c66915 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 + - > + GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/crd-ref-docs@${DAGGER_CRDGENREF_SHA} generate + --src . + --source-path api/v1 + --config-file docs/config.yaml + --renderer markdown + --templates-dir docs/markdown + file --path out.md export --path docs/src/plugin-barman-cloud.v1.md sources: - ./api/**/*.go - ./docs/config.yaml + - ./docs/markdown/**/*.tpl + - ./Taskfile.yml generates: - ./docs/src/plugin-barman-cloud.v1.md @@ -338,6 +348,7 @@ tasks: controller-gen: desc: Run controller-gen + run: once env: # renovate: datasource=git-refs depName=controller-gen lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main DAGGER_CONTROLLER_GEN_SHA: db65290569cb7723a32e72fcfb134668e7b998c8 diff --git a/api/v1/groupversion_info.go b/api/v1/groupversion_info.go index 8807c5a..228b87e 100644 --- a/api/v1/groupversion_info.go +++ b/api/v1/groupversion_info.go @@ -14,9 +14,6 @@ See the License for the specific language governing permissions and limitations under the License. */ -// Package v1 contains API Schema definitions for the barmancloud v1 API group -// +kubebuilder:object:generate=true -// +groupName=barmancloud.cnpg.io package v1 import ( diff --git a/docs/config.yaml b/docs/config.yaml index 4195d1a..146bfcc 100644 --- a/docs/config.yaml +++ b/docs/config.yaml @@ -1,24 +1,20 @@ -hiddenMemberFields: - - "TypeMeta" +processor: + ignoreGroupVersions: + - "GVK" + customMarkers: + - name: "optional" + target: field + ignoreFields: +# - "status$" + - "TypeMeta$" + ignoreTypes: + - "ObjectStoreList$" -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 +render: + # Version of Kubernetes to use when generating links to Kubernetes API documentation. + # renovate: datasource=git-refs depName=kubernetes/kubernetes lookupName=https://github.com/kubernetes/kubernetes + kubernetesVersion: 1.31 + knownTypes: + - name: BarmanObjectStoreConfiguration + package: github.com/cloudnative-pg/barman-cloud/pkg/api + link: https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration diff --git a/docs/markdown/gv_details.tpl b/docs/markdown/gv_details.tpl new file mode 100644 index 0000000..30ad0d7 --- /dev/null +++ b/docs/markdown/gv_details.tpl @@ -0,0 +1,19 @@ +{{- define "gvDetails" -}} +{{- $gv := . -}} + +## {{ $gv.GroupVersionString }} + +{{ $gv.Doc }} + +{{- if $gv.Kinds }} +### Resource Types +{{- range $gv.SortedKinds }} +- {{ $gv.TypeForKind . | markdownRenderTypeLink }} +{{- end }} +{{ end }} + +{{ range $gv.SortedTypes }} +{{ template "type" . }} +{{ end }} + +{{- end -}} diff --git a/docs/markdown/gv_list.tpl b/docs/markdown/gv_list.tpl new file mode 100644 index 0000000..a4d3dad --- /dev/null +++ b/docs/markdown/gv_list.tpl @@ -0,0 +1,15 @@ +{{- define "gvList" -}} +{{- $groupVersions := . -}} + +# API Reference + +## Packages +{{- range $groupVersions }} +- {{ markdownRenderGVLink . }} +{{- end }} + +{{ range $groupVersions }} +{{ template "gvDetails" . }} +{{ end }} + +{{- end -}} diff --git a/docs/markdown/members.tpl b/docs/markdown/members.tpl deleted file mode 100644 index d3bacd1..0000000 --- a/docs/markdown/members.tpl +++ /dev/null @@ -1,34 +0,0 @@ -{{ 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 deleted file mode 100644 index 345d032..0000000 --- a/docs/markdown/pkg.tpl +++ /dev/null @@ -1,43 +0,0 @@ -{{ 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 index 91f7621..525f7c1 100644 --- a/docs/markdown/type.tpl +++ b/docs/markdown/type.tpl @@ -1,37 +1,49 @@ -{{ define "type" }} +{{- define "type" -}} +{{- $type := . -}} +{{- if markdownShouldRenderType $type -}} -## {{ .Name.Name }} {#{{ .Anchor }}} +#### {{ $type.Name }} -{{ if eq .Kind "Alias" -}} -(Alias of `{{ .Underlying }}`) -{{ end }} +{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }} -{{- with .References }} -**Appears in:** -{{ range . }} -{{ if or .Referenced .IsExported -}} -- [{{ .DisplayName }}]({{ .Link }}) -{{ end -}} -{{- end -}} +{{ $type.Doc }} + +{{ if $type.Validation -}} +_Validation:_ +{{- range $type.Validation }} +- {{ . }} +{{- end }} {{- end }} -{{ if .GetComment -}} -{{ .GetComment }} -{{ end }} -{{ if .GetMembers -}} - - - - {{- /* . is a apiType */ -}} - {{- if .IsExported -}} -{{- /* Add apiVersion and kind rows if deemed necessary */}} - - - {{- end -}} +{{ if $type.References -}} +_Appears in:_ +{{- range $type.SortedReferences }} +- {{ markdownRenderTypeLink . }} +{{- end }} +{{- end }} + +{{ if $type.Members -}} +| Field | Description | Required | Default | Validation | +| --- | --- | --- | --- | --- | +{{ if $type.GVK -}} +| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | True | | | +| `kind` _string_ | `{{ $type.GVK.Kind }}` | True | | | +{{ end -}} + +{{ range $type.Members -}} +| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ if not .Markers.optional -}}True{{- end }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }}
{{ end }} | +{{ end -}} + +{{ end -}} + +{{ if $type.EnumValues -}} +| Field | Description | +| --- | --- | +{{ range $type.EnumValues -}} +| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} | +{{ end -}} +{{ 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/markdown/type_members.tpl b/docs/markdown/type_members.tpl new file mode 100644 index 0000000..041758a --- /dev/null +++ b/docs/markdown/type_members.tpl @@ -0,0 +1,8 @@ +{{- define "type_members" -}} +{{- $field := . -}} +{{- if eq $field.Name "metadata" -}} +Refer to Kubernetes API documentation for fields of `metadata`. +{{- else -}} +{{ markdownRenderFieldDoc $field.Doc }} +{{- end -}} +{{- end -}} diff --git a/docs/src/plugin-barman-cloud.v1.md b/docs/src/plugin-barman-cloud.v1.md index 0573d8f..99283c2 100644 --- a/docs/src/plugin-barman-cloud.v1.md +++ b/docs/src/plugin-barman-cloud.v1.md @@ -1,179 +1,104 @@ # API Reference -

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

+## Packages +- [barmancloud.cnpg.io/v1](#barmancloudcnpgiov1) -## Resource Types +## barmancloud.cnpg.io/v1 +Package v1 contains API Schema definitions for the barmancloud v1 API group -- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) - -## ObjectStore {#barmancloud-cnpg-io-v1-ObjectStore} +### Resource Types +- [ObjectStore](#objectstore) -

ObjectStore is the Schema for the objectstores API.

+#### InstanceSidecarConfiguration - - - - - - - - - - - - - - - -
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 -		 -

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

-
status
-ObjectStoreStatus -		 -

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

-
-## InstanceSidecarConfiguration {#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration} +InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods. -**Appears in:** -- [ObjectStoreSpec](#barmancloud-cnpg-io-v1-ObjectStoreSpec) +_Appears in:_ +- [ObjectStoreSpec](#objectstorespec) + +| Field | Description | Required | Default | Validation | +| --- | --- | --- | --- | --- | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | The environment to be explicitly passed to the sidecar | | | | +| `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the
system checks and enforces retention policies. | | 1800 | | -

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

+#### ObjectStore - - - - - - - - - - -
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} +ObjectStore is the Schema for the objectstores API. -**Appears in:** - -- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) -

ObjectStoreSpec defines the desired state of ObjectStore.

+ +| Field | Description | Required | Default | Validation | +| --- | --- | --- | --- | --- | +| `apiVersion` _string_ | `barmancloud.cnpg.io/v1` | True | | | +| `kind` _string_ | `ObjectStore` | True | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` _[ObjectStoreSpec](#objectstorespec)_ | 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 | True | | | +| `status` _[ObjectStoreStatus](#objectstorestatus)_ | 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 | | | | - - - - - - - - - - - - - -
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 -		 -

The configuration for the sidecar that runs in the instance pods

-
- -## ObjectStoreStatus {#barmancloud-cnpg-io-v1-ObjectStoreStatus} +#### ObjectStoreSpec -**Appears in:** -- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) +ObjectStoreSpec defines the desired state of ObjectStore. -

ObjectStoreStatus defines the observed state of ObjectStore.

+ +_Appears in:_ +- [ObjectStore](#objectstore) + +| Field | Description | Required | Default | Validation | +| --- | --- | --- | --- | --- | +| `configuration` _[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)_ | The configuration for the barman-cloud tool suite | True | | | +| `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. | | | Pattern: `^[1-9][0-9]*[dwm]$`
| +| `instanceSidecarConfiguration` _[InstanceSidecarConfiguration](#instancesidecarconfiguration)_ | The configuration for the sidecar that runs in the instance pods | | | | - - - - - - - -
FieldDescription
serverRecoveryWindow [Required]
-map[string]RecoveryWindow -		 -

ServerRecoveryWindow maps each server to its recovery window

-
- -## RecoveryWindow {#barmancloud-cnpg-io-v1-RecoveryWindow} +#### ObjectStoreStatus -**Appears in:** -- [ObjectStoreStatus](#barmancloud-cnpg-io-v1-ObjectStoreStatus) +ObjectStoreStatus defines the observed state of ObjectStore. -

RecoveryWindow represents the time span between the first + +_Appears in:_ +- [ObjectStore](#objectstore) + +| Field | Description | Required | Default | Validation | +| --- | --- | --- | --- | --- | +| `serverRecoveryWindow` _object (keys:string, values:[RecoveryWindow](#recoverywindow))_ | ServerRecoveryWindow maps each server to its recovery window | True | | | + + +#### RecoveryWindow + + + +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.

+server, defining the period during which data can be restored. + + + +_Appears in:_ +- [ObjectStoreStatus](#objectstorestatus) + +| Field | Description | Required | Default | Validation | +| --- | --- | --- | --- | --- | +| `firstRecoverabilityPoint` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#time-v1-meta)_ | The first recoverability point in a PostgreSQL server refers to
the earliest point in time to which the database can be
restored. | True | | | +| `lastSuccussfulBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#time-v1-meta)_ | The last successful backup time | True | | | - - - - - - - - - - -
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 diff --git a/renovate.json5 b/renovate.json5 index b41320d..718be81 100644 --- a/renovate.json5 +++ b/renovate.json5 @@ -16,7 +16,7 @@ "ignorePaths": [ "dagger/gotest/go.mod", "dagger/e2e/go.mod" - ], + ] }, "postUpdateOptions": [ "gomodTidy" @@ -36,7 +36,19 @@ "# renovate: datasource=(?[a-z-.]+?) depName=(?[^\\s]+?)(?: (?:lookupName|packageName)=(?[^\\s]+?))?(?: versioning=(?[^\\s]+?))?(?: extractVersion=(?[^\\s]+?))?(?: currentValue=(?[^\\s]+?))?\\s+[A-Za-z0-9_]+?_SHA\\s*:\\s*[\"']?(?[a-f0-9]+?)[\"']?\\s", "# renovate: datasource=(?[a-z-.]+?) depName=(?[^\\s]+?)(?: (?:lookupName|packageName)=(?[^\\s]+?))?(?: versioning=(?[^\\s]+?))?(?: extractVersion=(?[^\\s]+?))?\\s+[A-Za-z0-9_]+?_VERSION\\s*:\\s*[\"']?(?.+?)[\"']?\\s" ] - } + }, + { + "customType": "regex", + "fileMatch": [ + "(^docs/config\\.yaml$)" + ], + "matchStrings": [ + "# renovate: datasource=(?[a-z-.]+?) depName=(?[^\\s]+?)(?: (?:lookupName|packageName)=(?[^\\s]+?))?(?: versioning=(?[^\\s]+?))?(?: extractVersion=(?[^\\s]+?))?\\s+kubernetesVersion:\\s*[\"']?(?.+?)[\"']?\\s" + ], + // This is needed to limit renovate to update major.minor versions only. Having the patch breaks crd-ref-docs. + "versioningTemplate": "regex:(?\\d+)\\.(?\\d+)", + "extractVersionTemplate": "^(?v\\d+\\.\\d+)\\.\\d+$" + }, ], "pip-compile": { "fileMatch": ["(^|/)sidecar-requirements\\.txt$"]