[Maintenance] Add Grade Field (#1909)

Author: ajanikow

CHANGELOG.md

@@ -20,6 +20,7 @@
 - (Bugfix) Fix Checksum Calculation
 - (Bugfix) Implement Missing Group Tolerations
 - (Feature) (Platform) OpenID Logout Endpoints
+- (Maintenance) Grade Doc Field
 
 ## [1.2.48](https://github.com/arangodb/kube-arangodb/tree/1.2.48) (2025-05-08)
 - (Maintenance) Extend Documentation

docs/api/ArangoDeployment.V1.md

@@ -3171,7 +3171,12 @@ UID keeps the information about object UID
 
 ### .spec.gateway.authentication.type
 
-Type: `string` <sup>[\[ref\]](https://github.com/arangodb/kube-arangodb/blob/1.2.48/pkg/apis/deployment/v1/deployment_spec_gateway_authentication.go#L51)</sup>
+Type: `string` <sup>[\[ref\]](https://github.com/arangodb/kube-arangodb/blob/1.2.48/pkg/apis/deployment/v1/deployment_spec_gateway_authentication.go#L53)</sup>
+
+> [!WARNING]
+> ***ALPHA***
+> 
+> **Feature under active development**
 
 Type defines the Authentication Type
 

internal/doc_definition_test.go

@@ -23,6 +23,9 @@ package internal
 import (
 	"sort"
 	goStrings "strings"
+
+	"github.com/arangodb/kube-arangodb/pkg/util/errors"
+	"github.com/arangodb/kube-arangodb/pkg/util/strings"
 )
 
 type DocDefinitions []DocDefinition
@@ -36,7 +39,7 @@ type DocDefinition struct {
 
 	Docs []string
 
-	Deprecated []string
+	Grade *DocDefinitionGradeDefinition
 
 	Links []string
 
@@ -59,3 +62,58 @@ func (d DocDefinitions) Sort() {
 		return a < b
 	})
 }
+
+func NewDocDefinitionGradeDefinition(lines ...string) (*DocDefinitionGradeDefinition, error) {
+	if len(lines) == 0 {
+		return nil, nil
+	}
+
+	start := lines[0]
+
+	var ret DocDefinitionGradeDefinition
+
+	grade, err := DocDefinitionGradeFromString(start)
+	if err != nil {
+		return nil, err
+	}
+
+	ret.Grade = grade
+
+	if len(lines) > 1 {
+		ret.Message = lines[1:]
+	}
+
+	return &ret, nil
+}
+
+type DocDefinitionGradeDefinition struct {
+	Grade   DocDefinitionGrade
+	Message []string
+}
+
+type DocDefinitionGrade int
+
+const (
+	DocDefinitionGradeAlpha DocDefinitionGrade = iota
+	DocDefinitionGradeBeta
+	DocDefinitionGradeProduction
+	DocDefinitionGradeDeprecating
+	DocDefinitionGradeDeprecated
+)
+
+func DocDefinitionGradeFromString(in string) (DocDefinitionGrade, error) {
+	switch strings.ToLower(in) {
+	case "alpha":
+		return DocDefinitionGradeAlpha, nil
+	case "beta":
+		return DocDefinitionGradeBeta, nil
+	case "production":
+		return DocDefinitionGradeProduction, nil
+	case "deprecating":
+		return DocDefinitionGradeDeprecating, nil
+	case "deprecated":
+		return DocDefinitionGradeAlpha, nil
+	default:
+		return 0, errors.Errorf("Unable to parse grade: %s", in)
+	}
+}

internal/docs_parser_test.go

@@ -74,13 +74,14 @@ func parseDocDefinition(t *testing.T, root, path, typ string, field *ast.Field,
 		def.Important = util.NewType[string](important[0])
 	}
 
-	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 {
+	if docs := extractDocumentation(field); len(docs) > 0 {
 		def.Docs = docs
-		def.Deprecated = dep
+	}
+
+	if grade, err := extractGrade(field); err != nil {
+		require.Fail(t, fmt.Sprintf("Error while getting grade for %s: %s", path, err.Error()))
+	} else {
+		def.Grade = grade
 	}
 
 	file := fs.File(field.Pos())
@@ -250,40 +251,79 @@ func extract(n *ast.Field, tag string) ([]string, bool) {
 	return ret, len(ret) > 0
 }
 
-func extractNotTags(n *ast.Field) ([]string, []string, bool, error) {
-	if n.Doc == nil {
-		return nil, nil, false, nil
+func extractGrade(n *ast.Field) (*DocDefinitionGradeDefinition, error) {
+	deprecatedGrade, err := extractDeprecated(n)
+	if err != nil {
+		return nil, err
 	}
 
-	var ret, dep []string
+	var grade *DocDefinitionGradeDefinition
 
-	var deprecated bool
+	if v, ok := extract(n, "grade"); ok {
+		grade, err = NewDocDefinitionGradeDefinition(v...)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	if deprecatedGrade != nil && grade != nil {
+		return nil, errors.Errorf("Only one way of defining grade should be visible")
+	}
 
+	if deprecatedGrade != nil {
+		return deprecatedGrade, nil
+	}
+
+	if grade != nil {
+		return grade, nil
+	}
+
+	return nil, nil
+}
+
+func extractDeprecated(n *ast.Field) (*DocDefinitionGradeDefinition, error) {
+	if n == nil || n.Doc == nil {
+		return nil, nil
+	}
 	for _, c := range n.Doc.List {
 		if goStrings.HasPrefix(c.Text, "// ") {
 			if goStrings.HasPrefix(c.Text, "// Deprecated") {
 				if !goStrings.HasPrefix(c.Text, "// Deprecated: ") {
-					return nil, nil, false, errors.Errorf("Invalid deprecated field")
+					return nil, errors.Errorf("Invalid deprecated field")
 				}
 			}
 			if goStrings.HasPrefix(c.Text, "// Deprecated:") {
-				deprecated = true
-				dep = append(dep, goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// Deprecated:")))
-				continue
+				return &DocDefinitionGradeDefinition{
+					Grade:   DocDefinitionGradeDeprecated,
+					Message: []string{goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// Deprecated:"))},
+				}, nil
 			}
+		}
+	}
 
-			if !goStrings.HasPrefix(c.Text, "// +doc/") {
-				v := goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// "))
-				if deprecated {
-					dep = append(dep, v)
-				} else {
-					ret = append(ret, v)
-				}
+	return nil, nil
+}
+
+func extractDocumentation(n *ast.Field) []string {
+	if n.Doc == nil {
+		return nil
+	}
+
+	var ret []string
+
+	for _, c := range n.Doc.List {
+		if goStrings.HasPrefix(c.Text, "// ") {
+			if goStrings.HasPrefix(c.Text, "// +doc/") {
+				continue
+			}
+			if goStrings.HasPrefix(c.Text, "// Deprecated") {
+				continue
 			}
+			ret = append(ret, goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// ")))
 		}
 	}
 
-	return ret, dep, len(ret) > 0 || len(dep) > 0, nil
+	return ret
 }
 
 // isSimpleType returns the OpenAPI-compatible type name, type format and boolean indicating if this is simple type or not

internal/docs_test.go

@@ -70,14 +70,33 @@ 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)
+		if grade := el.Grade; grade != nil {
+			switch grade.Grade {
+			case DocDefinitionGradeDeprecated:
+				write(t, out, "> [!WARNING]\n")
+				write(t, out, "> ***DEPRECATED***\n")
+				write(t, out, "> \n")
+				for _, line := range grade.Message {
+					write(t, out, "> **%s**\n", line)
+				}
+				write(t, out, "\n")
+			case DocDefinitionGradeAlpha:
+				write(t, out, "> [!WARNING]\n")
+				write(t, out, "> ***ALPHA***\n")
+				write(t, out, "> \n")
+				for _, line := range grade.Message {
+					write(t, out, "> **%s**\n", line)
+				}
+				write(t, out, "\n")
+			case DocDefinitionGradeBeta:
+				write(t, out, "> [!IMPORTANT]\n")
+				write(t, out, "> ***BETA***\n")
+				write(t, out, "> \n")
+				for _, line := range grade.Message {
+					write(t, out, "> **%s**\n", line)
+				}
+				write(t, out, "\n")
 			}
-			write(t, out, "\n")
 		}
 
 		if d := el.Important; d != nil {

pkg/apis/deployment/v1/deployment_spec_gateway_authentication.go

@@ -48,6 +48,8 @@ const (
 type DeploymentSpecGatewayAuthentication struct {
 	// Type defines the Authentication Type
 	// +doc/enum: OpenID|Configure OpenID Authentication Type
+	// +doc/grade: Alpha
+	// +doc/grade: Feature under active development
 	Type DeploymentSpecGatewayAuthenticationType `json:"type"`
 
 	// Secret defines the secret with the integration configuration

pkg/apis/deployment/v2alpha1/deployment_spec_gateway_authentication.go

@@ -48,6 +48,8 @@ const (
 type DeploymentSpecGatewayAuthentication struct {
 	// Type defines the Authentication Type
 	// +doc/enum: OpenID|Configure OpenID Authentication Type
+	// +doc/grade: Alpha
+	// +doc/grade: Feature under active development
 	Type DeploymentSpecGatewayAuthenticationType `json:"type"`
 
 	// Secret defines the secret with the integration configuration