docs: fix minor issues (cloudnative-pg#5903)

* Mark all omitempty fields in the API as optional, so they won't appear as required in the documentation * Fix broken links to structs now in the barman-cloud API * Make Database resource appear in the API resource types Closes cloudnative-pg#5904 Signed-off-by: Francesco Canovai <[email protected]> Signed-off-by: Gabriele Quaresima <[email protected]> Co-authored-by: Gabriele Quaresima <[email protected]>
EnterpriseDB · Oct 24, 2024 · 2e90e9d · 2e90e9d
1 parent 52b991f
commit 2e90e9d
Show file tree

Hide file tree

Showing 10 changed files with 124 additions and 73 deletions.
diff --git a/api/v1/backup_types.go b/api/v1/backup_types.go
@@ -182,6 +182,7 @@ type BackupSnapshotElementStatus struct {
 
 	// TablespaceName is the name of the snapshotted tablespace. Only set
 	// when type is PG_TABLESPACE
+	// +optional
 	TablespaceName string `json:"tablespaceName,omitempty"`
 }
 
@@ -285,9 +286,11 @@ type BackupStatus struct {
 	Method BackupMethod `json:"method,omitempty"`
 
 	// Whether the backup was online/hot (`true`) or offline/cold (`false`)
+	// +optional
 	Online *bool `json:"online,omitempty"`
 
 	// A map containing the plugin metadata
+	// +optional
 	PluginMetadata map[string]string `json:"pluginMetadata,omitempty"`
 }
 
@@ -333,6 +336,7 @@ type BackupList struct {
 	metav1.TypeMeta `json:",inline"`
 	// Standard list metadata.
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+	// +optional
 	metav1.ListMeta `json:"metadata,omitempty"`
 	// List of backups
 	Items []Backup `json:"items"`

diff --git a/api/v1/cluster_types.go b/api/v1/cluster_types.go
@@ -382,6 +382,7 @@ type ClusterSpec struct {
 
 	// EphemeralVolumesSizeLimit allows the user to set the limits for the ephemeral
 	// volumes
+	// +optional
 	EphemeralVolumesSizeLimit *EphemeralVolumesSizeLimitConfiguration `json:"ephemeralVolumesSizeLimit,omitempty"`
 
 	// Name of the priority class which will be used in every generated Pod, if the PriorityClass
@@ -473,6 +474,7 @@ type ClusterSpec struct {
 
 	// The plugins configuration, containing
 	// any plugin to be loaded with the corresponding configuration
+	// +optional
 	Plugins PluginConfigurationList `json:"plugins,omitempty"`
 }
 
@@ -547,9 +549,11 @@ const (
 // storage
 type EphemeralVolumesSizeLimitConfiguration struct {
 	// Shm is the size limit of the shared memory volume
+	// +optional
 	Shm *resource.Quantity `json:"shm,omitempty"`
 
 	// TemporaryData is the size limit of the temporary data volume
+	// +optional
 	TemporaryData *resource.Quantity `json:"temporaryData,omitempty"`
 }
 
@@ -712,6 +716,7 @@ type ClusterStatus struct {
 
 	// LastPromotionToken is the last verified promotion token that
 	// was used to promote a replica cluster
+	// +optional
 	LastPromotionToken string `json:"lastPromotionToken,omitempty"`
 
 	// How many PVCs have been created by this cluster
@@ -849,6 +854,7 @@ type ClusterStatus struct {
 	Image string `json:"image,omitempty"`
 
 	// PluginStatus is the status of the loaded plugins
+	// +optional
 	PluginStatus []PluginStatus `json:"pluginStatus,omitempty"`
 
 	// SwitchReplicaClusterStatus is the status of the switch to replica cluster
@@ -967,10 +973,12 @@ type PgBouncerIntegrationStatus struct {
 type ReplicaClusterConfiguration struct {
 	// Self defines the name of this cluster. It is used to determine if this is a primary
 	// or a replica cluster, comparing it with `primary`
+	// +optional
 	Self string `json:"self,omitempty"`
 
 	// Primary defines which Cluster is defined to be the primary in the distributed PostgreSQL cluster, based on the
 	// topology specified in externalClusters
+	// +optional
 	Primary string `json:"primary,omitempty"`
 
 	// The name of the external cluster which is the replication origin
@@ -981,17 +989,20 @@ type ReplicaClusterConfiguration struct {
 	// existing cluster. Replica cluster can be created from a recovery
 	// object store or via streaming through pg_basebackup.
 	// Refer to the Replica clusters page of the documentation for more information.
+	// +optional
 	Enabled *bool `json:"enabled,omitempty"`
 
 	// A demotion token generated by an external cluster used to
 	// check if the promotion requirements are met.
+	// +optional
 	PromotionToken string `json:"promotionToken,omitempty"`
 
 	// When replica mode is enabled, this parameter allows you to replay
 	// transactions only when the system time is at least the configured
 	// time past the commit time. This provides an opportunity to correct
 	// data loss errors. Note that when this parameter is set, a promotion
 	// token cannot be used.
+	// +optional
 	MinApplyDelay *metav1.Duration `json:"minApplyDelay,omitempty"`
 }
 
@@ -2005,6 +2016,7 @@ type ManagedServices struct {
 	// +optional
 	DisabledDefaultServices []ServiceSelectorType `json:"disabledDefaultServices,omitempty"`
 	// Additional is a list of additional managed services specified by the user.
+	// +optional
 	Additional []ManagedService `json:"additional,omitempty"`
 }
 
@@ -2018,6 +2030,7 @@ type ManagedService struct {
 
 	// UpdateStrategy describes how the service differences should be reconciled
 	// +kubebuilder:default:="patch"
+	// +optional
 	UpdateStrategy ServiceUpdateStrategy `json:"updateStrategy,omitempty"`
 
 	// ServiceTemplate is the template specification for the service.
@@ -2047,6 +2060,7 @@ type PluginConfiguration struct {
 	Enabled *bool `json:"enabled,omitempty"`
 
 	// Parameters is the configuration of the plugin
+	// +optional
 	Parameters map[string]string `json:"parameters,omitempty"`
 }
 
@@ -2061,21 +2075,26 @@ type PluginStatus struct {
 
 	// Capabilities are the list of capabilities of the
 	// plugin
+	// +optional
 	Capabilities []string `json:"capabilities,omitempty"`
 
 	// OperatorCapabilities are the list of capabilities of the
 	// plugin regarding the reconciler
+	// +optional
 	OperatorCapabilities []string `json:"operatorCapabilities,omitempty"`
 
 	// WALCapabilities are the list of capabilities of the
 	// plugin regarding the WAL management
+	// +optional
 	WALCapabilities []string `json:"walCapabilities,omitempty"`
 
 	// BackupCapabilities are the list of capabilities of the
 	// plugin regarding the Backup management
+	// +optional
 	BackupCapabilities []string `json:"backupCapabilities,omitempty"`
 
 	// Status contain the status reported by the plugin through the SetStatusInCluster interface
+	// +optional
 	Status string `json:"status,omitempty"`
 }
 
@@ -2204,6 +2223,7 @@ type ClusterList struct {
 	metav1.TypeMeta `json:",inline"`
 	// Standard list metadata.
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+	// +optional
 	metav1.ListMeta `json:"metadata,omitempty"`
 	// List of clusters
 	Items []Cluster `json:"items"`

diff --git a/api/v1/common_types.go b/api/v1/common_types.go
@@ -25,6 +25,7 @@ const VolumeSnapshotKind = "VolumeSnapshot"
 // not using the core data types.
 type Metadata struct {
 	// The name of the resource. Only supported for certain types
+	// +optional
 	Name string `json:"name,omitempty"`
 
 	// Map of string keys and values that can be used to organize and categorize

diff --git a/api/v1/database_types.go b/api/v1/database_types.go
@@ -132,13 +132,17 @@ type DatabaseStatus struct {
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
 	// Ready is true if the database was reconciled correctly
+	// +optional
 	Ready bool `json:"ready,omitempty"`
 
 	// Error is the reconciliation error message
+	// +optional
 	Error string `json:"error,omitempty"`
 }
 
+// +genclient
 // +kubebuilder:object:root=true
+// +kubebuilder:storageversion
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 // +kubebuilder:printcolumn:name="Cluster",type="string",JSONPath=".spec.cluster.name"

diff --git a/api/v1/pooler_types.go b/api/v1/pooler_types.go
@@ -260,6 +260,7 @@ type Pooler struct {
 // PoolerList contains a list of Pooler
 type PoolerList struct {
 	metav1.TypeMeta `json:",inline"`
+	// +optional
 	metav1.ListMeta `json:"metadata,omitempty"`
 	Items           []Pooler `json:"items"`
 }

diff --git a/api/v1/scheduledbackup_types.go b/api/v1/scheduledbackup_types.go
@@ -125,6 +125,7 @@ type ScheduledBackupList struct {
 	metav1.TypeMeta `json:",inline"`
 	// Standard list metadata.
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+	// +optional
 	metav1.ListMeta `json:"metadata,omitempty"`
 	// List of clusters
 	Items []ScheduledBackup `json:"items"`

diff --git a/docs/config.yaml b/docs/config.yaml
@@ -1,5 +1,6 @@
 hiddenMemberFields:
   - "TypeMeta"
+  - "synchronizeReplicasCache"
 
 externalPackages:
   - match: ^github\.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1\.RelabelConfig$
@@ -31,7 +32,14 @@ externalPackages:
 
 hideTypePatterns:
   - "ParseError$"
-  - "List$"
+  # We cannot exclude all `List$` because we declare PluginConfigurationList
+  - "BackupList$"
+  - "ClusterList$"
+  - "ClusterImageCatalogList$"
+  - "DatabaseList$"
+  - "ImageCatalogList$"
+  - "PoolerList$"
+  - "ScheduledBackupList$"
 
 markdownDisabled: false
 

diff --git a/docs/src/backup_barmanobjectstore.md b/docs/src/backup_barmanobjectstore.md
@@ -96,9 +96,9 @@ algorithms via `barman-cloud-backup` (for backups) and
 * snappy
 
 The compression settings for backups and WALs are independent. See the
-[DataBackupConfiguration](cloudnative-pg.v1.md#postgresql-cnpg-io-v1-DataBackupConfiguration) and
-[WALBackupConfiguration](cloudnative-pg.v1.md#postgresql-cnpg-io-v1-WalBackupConfiguration) sections in
-the API reference.
+[DataBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration) and
+[WALBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration) sections in
+the barman-cloud API reference.
 
 It is important to note that archival time, restore time, and size change
 between the algorithms, so the compression algorithm should be chosen according
@@ -198,4 +198,4 @@ spec:
         additionalCommandArgs:
         - "--max-concurrency=1"
         - "--read-timeout=60"
-```
+```