[Documentation] Extract Important and Deprecated fields (#1605)

Author: ajanikow

Makefile

@@ -727,7 +727,7 @@ init: vendor tools update-generated $(BIN)
 .PHONY: tools-min
 tools-min: update-vendor
 	@echo ">> Fetching golangci-lint linter"
-	@GOBIN=$(GOPATH)/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.52.2
+	@GOBIN=$(GOPATH)/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.56.2
 	@echo ">> Fetching goimports"
 	@GOBIN=$(GOPATH)/bin go install golang.org/x/tools/cmd/goimports@0bb7e5c47b1a31f85d4f173edc878a8e049764a5
 	@echo ">> Fetching license check"

docs/api/ArangoDeployment.V1.md

@@ -74,7 +74,10 @@ Checksum keep the Pod Spec Checksum (with ignored fields).
 
 Type: `string` <sup>[\[ref\]](https://github.com/arangodb/kube-arangodb/blob/1.2.38/pkg/apis/deployment/v1/arango_member_pod_template.go#L63)</sup>
 
-Deprecated: Endpoint is not saved into the template
+> [!WARNING]
+> ***DEPRECATED***
+> 
+> **Endpoint is not saved into the template**
 
 ***
 

docs/api/ArangoMember.V1.md

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2023 ArangoDB GmbH, Cologne, Germany
+// Copyright 2023-2024 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -36,6 +36,8 @@ type DocDefinition struct {
 
 	Docs []string
 
+	Deprecated []string
+
 	Links []string
 
 	Important *string

internal/doc_definition_test.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2023 ArangoDB GmbH, Cologne, Germany
+// Copyright 2023-2024 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -35,6 +35,7 @@ import (
 	openapi "k8s.io/kube-openapi/pkg/common"
 
 	"github.com/arangodb/kube-arangodb/pkg/util"
+	"github.com/arangodb/kube-arangodb/pkg/util/errors"
 )
 
 const (
@@ -73,10 +74,13 @@ func parseDocDefinition(t *testing.T, root, path, typ string, field *ast.Field,
 		def.Important = util.NewType[string](important[0])
 	}
 
-	if docs, ok := extractNotTags(field); !ok {
+	if docs, dep, ok, err := extractNotTags(field); err != nil {
+		require.Fail(t, fmt.Sprintf("Error while getting tags for %s: %s", path, err.Error()))
+	} else if !ok {
 		println(def.Path, " is missing documentation!")
 	} else {
 		def.Docs = docs
+		def.Deprecated = dep
 	}
 
 	file := fs.File(field.Pos())
@@ -246,22 +250,40 @@ func extract(n *ast.Field, tag string) ([]string, bool) {
 	return ret, len(ret) > 0
 }
 
-func extractNotTags(n *ast.Field) ([]string, bool) {
+func extractNotTags(n *ast.Field) ([]string, []string, bool, error) {
 	if n.Doc == nil {
-		return nil, false
+		return nil, nil, false, nil
 	}
 
-	var ret []string
+	var ret, dep []string
+
+	var deprecated bool
 
 	for _, c := range n.Doc.List {
 		if strings.HasPrefix(c.Text, "// ") {
+			if strings.HasPrefix(c.Text, "// Deprecated") {
+				if !strings.HasPrefix(c.Text, "// Deprecated: ") {
+					return nil, nil, false, errors.Errorf("Invalid deprecated field")
+				}
+			}
+			if strings.HasPrefix(c.Text, "// Deprecated:") {
+				deprecated = true
+				dep = append(dep, strings.TrimSpace(strings.TrimPrefix(c.Text, "// Deprecated:")))
+				continue
+			}
+
 			if !strings.HasPrefix(c.Text, "// +doc/") {
-				ret = append(ret, strings.TrimPrefix(c.Text, "// "))
+				v := strings.TrimSpace(strings.TrimPrefix(c.Text, "// "))
+				if deprecated {
+					dep = append(dep, v)
+				} else {
+					ret = append(ret, v)
+				}
 			}
 		}
 	}
 
-	return ret, len(ret) > 0
+	return ret, dep, len(ret) > 0 || len(dep) > 0, nil
 }
 
 // isSimpleType returns the OpenAPI-compatible type name, type format and boolean indicating if this is simple type or not

internal/docs_parser_test.go

@@ -61,8 +61,19 @@ func (d DocDefinitions) RenderMarkdown(t *testing.T, repositoryPath string) []by
 		write(t, out, "### %s\n\n", el.Path)
 		write(t, out, "Type: `%s` <sup>[\\[ref\\]](%s/%s#L%d)</sup>\n\n", el.Type, repositoryPath, el.File, el.Line)
 
+		if d := el.Deprecated; len(d) > 0 {
+			write(t, out, "> [!WARNING]\n")
+			write(t, out, "> ***DEPRECATED***\n")
+			write(t, out, "> \n")
+			for _, line := range d {
+				write(t, out, "> **%s**\n", line)
+			}
+			write(t, out, "\n")
+		}
+
 		if d := el.Important; d != nil {
-			write(t, out, "**Important**: %s\n\n", *d)
+			write(t, out, "> [!IMPORTANT]\n")
+			write(t, out, "> **%s**\n\n", *d)
 		}
 
 		if len(el.Docs) > 0 {

internal/docs_test.go

@@ -79,15 +79,23 @@ type MetricsSpec struct {
 	// +doc/default: false
 	// +doc/link: Metrics collection|../metrics.md
 	Enabled *bool `json:"enabled,omitempty"`
-	// deprecated
-	Image          *string                   `json:"image,omitempty"`
+
+	// Image used for the Metrics Sidecar
+	//
+	// Deprecated: Image is now extracted from Operator Pod
+	Image *string `json:"image,omitempty"`
+
 	Authentication MetricsAuthenticationSpec `json:"authentication,omitempty"`
 	// Resources holds resource requests & limits
 	// +doc/type: core.ResourceRequirements
 	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core
 	Resources core.ResourceRequirements `json:"resources,omitempty"`
-	// deprecated
+
+	// Mode define metrics exported mode
+	//
+	// Deprecated: Not used anymore
 	Mode *MetricsMode `json:"mode,omitempty"`
+
 	// TLS defines if TLS should be enabled on Metrics exporter endpoint.
 	// This option will enable TLS only if TLS is enabled on ArangoDeployment,
 	// otherwise `true` value will not take any effect.

pkg/apis/deployment/v1/deployment_metrics_spec.go

@@ -85,24 +85,24 @@ type MemberStatus struct {
 	// SecondaryPersistentVolumeClaim keeps information about PVC for SecondaryPod
 	SecondaryPersistentVolumeClaim *MemberPersistentVolumeClaimStatus `json:"secondaryPersistentVolumeClaim,omitempty"`
 
-	// deprecated
+	// Deprecated
 	// SideCarSpecs contains map of specifications specified for side cars
 	// +doc/type: map[string]core.Container
 	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#container-v1-core
 	SideCarSpecs map[string]core.Container `json:"sidecars-specs,omitempty"`
-	// deprecated
+	// Deprecated
 	// PodName holds the name of the Pod that currently runs this member
 	PodName string `json:"podName,omitempty"`
-	// deprecated
+	// Deprecated
 	// PodUID holds the UID of the Pod that currently runs this member
 	PodUID types.UID `json:"podUID,omitempty"`
-	// deprecated
+	// Deprecated
 	// PodSpecVersion holds the checksum of Pod spec that currently runs this member. Used to rotate pods
 	PodSpecVersion string `json:"podSpecVersion,omitempty"`
-	// deprecated
+	// Deprecated
 	// PersistentVolumeClaimName holds the name of the persistent volume claim used for this member (if any).
 	PersistentVolumeClaimName string `json:"persistentVolumeClaimName,omitempty"`
-	// deprecated
+	// Deprecated
 	// Endpoint definition how member should be reachable
 	Endpoint *string `json:"-"`
 }
@@ -156,7 +156,7 @@ func (s *MemberStatus) RemoveTerminationsBefore(timestamp time.Time) int {
 	}
 }
 
-// deprecated
+// Deprecated
 func (s *MemberStatus) GetEndpoint(defaultEndpoint string) string {
 	if s == nil || s.Endpoint == nil {
 		return defaultEndpoint

pkg/apis/deployment/v1/member_status.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2024 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -57,8 +57,9 @@ func (a *ArangoDeploymentRebalancerSpec) GetParallelMoves() int {
 }
 
 type ArangoDeploymentRebalancerReadersSpec struct {
-	// deprecated does not work in Rebalancer V2
 	// Count Enable Shard Count machanism
+	//
+	// Deprecated: does not work in Rebalancer V2
 	Count *bool `json:"count,omitempty"`
 }
 

pkg/apis/deployment/v1/rebalancer_spec.go

@@ -88,6 +88,8 @@ type ServerGroupSpec struct {
 	// SchedulerName define scheduler name used for group
 	SchedulerName *string `json:"schedulerName,omitempty"`
 	// StorageClassName specifies the classname for storage of the servers.
+	//
+	// Deprecated: Use VolumeClaimTemplate instead.
 	StorageClassName *string `json:"storageClassName,omitempty"`
 	// Resources holds resource requests & limits
 	// +doc/type: core.ResourceRequirements
@@ -168,7 +170,9 @@ type ServerGroupSpec struct {
 	// +doc/enum: rotate|Pod will be shutdown and PVC will be resized (AKS)
 	// +doc/default: runtime
 	VolumeResizeMode *PVCResizeMode `json:"pvcResizeMode,omitempty"`
-	// Deprecated: VolumeAllowShrink allows shrink the volume
+	// VolumeAllowShrink allows shrinking of the volume
+	//
+	// Deprecated: Not used anymore
 	VolumeAllowShrink *bool `json:"volumeAllowShrink,omitempty"`
 	// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
 	// +doc/type: core.PodAntiAffinity