Add depreaction annotations to variables

Signed-off-by: Christian Richter <crichter@owncloud.com>

changelog/unreleased/add-deprecation-annotation.md

@@ -0,0 +1,14 @@
+Enhancement: Add deprecation annotation
+
+We have added the ability to annotate variables in case of deprecations:
+
+Example:
+
+`services/nats/pkg/config/config.go`
+
+```
+Host string `yaml:"host" env:"NATS_HOST_ADDRESS,NATS_NATS_HOST" desc:"Bind address." deprecationVersion:"1.6.2" removalVersion:"1.7.5" deprecationInfo:"the name is ugly" deprecationReplacement:"NATS_HOST_ADDRESS"`
+```
+
+https://github.com/owncloud/ocis/issues/3917
+https://github.com/owncloud/ocis/pull/5143

docs/helpers/adoc-generator.go.tmpl

@@ -20,12 +20,22 @@ type ConfigField struct {
 	DefaultValue string
 	Type         string
 	Description  string
-	VersionInfo	 string
+	VersionInfo  string
+	IsDeprecated bool
+}
+
+type DeprecationField struct {
+	DeprecationVersion     string
+	DeprecationInfo        string
+	DeprecationReplacement string
+	RemovalVersion         string
 }
 
 type templateData struct {
-	ExtensionName string
-	Fields        []ConfigField
+	ExtensionName   string
+	Fields          []ConfigField
+	Deprecations    []DeprecationField
+	HasDeprecations bool
 }
 
 func main() {
@@ -39,6 +49,7 @@ replacer := strings.NewReplacer(
 		"/pkg/config/defaults", "",
 	)
 var fields []ConfigField
+var deprecations []DeprecationField
 var targetFile *os.File
 tpl := template.Must(template.New("").Parse(string(content)))
 
@@ -50,8 +61,13 @@ m := map[string]interface{}{
 
     targetFolder := "../../docs/services/_includes/adoc/"
     for pkg, conf := range m {
-	fields = GetAnnotatedVariables(conf)
-	if len(fields) > 0 {
+	fields, deprecations = GetAnnotatedVariables(conf)
+	var hasDeprecations bool
+	if len(deprecations) > 0 {
+		hasDeprecations = true
+	}
+
+	if len(fields) > 0 || len(deprecations) > 0 {
 	fmt.Printf("... %s\n", pkg)
 		targetFile, err = os.Create(filepath.Join(targetFolder, replacer.Replace(pkg) + "_configvars.adoc"))
 		if err != nil {
@@ -62,6 +78,8 @@ m := map[string]interface{}{
 		td := templateData{
 			ExtensionName: replacer.Replace(pkg),
 			Fields:        fields,
+			Deprecations: deprecations,
+			HasDeprecations: hasDeprecations ,
 		}
 		if err := tpl.Execute(targetFile, td); err != nil {
 			log.Fatalf("Failed to execute template: %s", err)
@@ -71,11 +89,12 @@ m := map[string]interface{}{
 	fmt.Println("done")
 }
 
-func GetAnnotatedVariables(s interface{}) []ConfigField {
+func GetAnnotatedVariables(s interface{}) ([]ConfigField, []DeprecationField) {
 	t := reflect.TypeOf(s)
 	v := reflect.ValueOf(s)
 
 	var fields []ConfigField
+	var deprecations []DeprecationField
 	for i := 0; i < t.NumField(); i++ {
 		field := t.Field(i)
 		value := v.Field(i)
@@ -84,10 +103,33 @@ func GetAnnotatedVariables(s interface{}) []ConfigField {
 		default:
 			desc := field.Tag.Get("desc")
 			env, ok := field.Tag.Lookup("env")
+			isDeprecated := false
 			if !ok {
 				continue
 			}
-			v := fmt.Sprintf("%v", value.Interface())			
+			deprecationVersion, ok := field.Tag.Lookup("deprecationVersion")
+			if !ok {
+				deprecationVersion = ""
+			}
+			removalVersion, ok := field.Tag.Lookup("removalVersion")
+			if !ok {
+				removalVersion = ""
+			}
+			deprecationInfo, ok := field.Tag.Lookup("deprecationInfo")
+			if !ok {
+				deprecationInfo = ""
+			}
+			deprecationReplacement, ok := field.Tag.Lookup("deprecationReplacement")
+			if !ok {
+				deprecationReplacement = ""
+			}
+			if deprecationVersion != "" ||
+				removalVersion != "" ||
+				deprecationInfo != "" ||
+				deprecationReplacement != "" {
+				isDeprecated = true
+			}
+			v := fmt.Sprintf("%v", value.Interface())
 			td := strings.Split(env, ";")
 			// re := regexp.MustCompile(`^(https?:\/\/)`)
 			// v = re.ReplaceAllString(v,"\\$1")
@@ -99,18 +141,38 @@ func GetAnnotatedVariables(s interface{}) []ConfigField {
 			if typeName == "" {
 				typeName = value.Type().String()
 			}
-			fields = append(fields, ConfigField{EnvVars: td, DefaultValue: v, Description: desc, Type: typeName})
+			fields = append(fields,
+				ConfigField{
+					EnvVars:      td,
+					DefaultValue: v,
+					Description:  desc,
+					Type:         typeName,
+					IsDeprecated: isDeprecated,
+				})
+			if isDeprecated {
+				deprecations = append(deprecations,
+					DeprecationField{
+						DeprecationVersion:     deprecationVersion,
+						DeprecationInfo:        deprecationInfo,
+						DeprecationReplacement: deprecationReplacement,
+						RemovalVersion:         removalVersion,
+					})
+			}
 		case reflect.Ptr:
 			// PolicySelectors in the Proxy are being skipped atm
 			// they are not configurable via env vars, if that changes
 			// they are probably added to the Sanitize() function
 			// and this should not be an issue then
 			if !value.IsZero() && value.Elem().CanInterface() {
-				fields = append(fields, GetAnnotatedVariables(value.Elem().Interface())...)
+				f, d := GetAnnotatedVariables(value.Elem().Interface())
+				fields = append(fields, f...)
+				deprecations = append(deprecations, d...)
 			}
 		case reflect.Struct:
-			fields = append(fields, GetAnnotatedVariables(value.Interface())...)
+			f, d := GetAnnotatedVariables(value.Interface())
+			fields = append(fields, f...)
+			deprecations = append(deprecations, d...)
 		}
 	}
-	return fields
+	return fields, deprecations
 }

docs/templates/ADOC.tmpl

@@ -1,17 +1,43 @@
+// set the attribute to true or leave empty, true without any quotes.
+:show-deprecation: {{ .HasDeprecations }}
+
+ifeval::[{show-deprecation} == true]
+[[deprecation-note]]
+[caption=]
+[width="100%",cols="~,~,~,~",options="header"]
+| ===                    |
+| Deprecation Version    |
+| Removal Version        |
+| Deprecation Info       |
+| Deprecation Replacment |
+
+{{- range .Deprecations }}
+| {{ .DeprecationVersion }}
+| {{ .RemovalVersion }}
+| {{ .DeprecationInfo }}
+| {{ .DeprecationReplacement }}
+| ===
+{{- end }}
+endif::[]
+
 [caption=]
 .Environment variables for the {{ .ExtensionName }} service
 [width="100%",cols="~,~,~,~",options="header"]
-|===
-| Name
-| Type
-| Default Value
-| Description
+| ===           |
+| Name          |
+| Type          |
+| Default Value |
+| Description   |
 
 {{- range .Fields}}
-| {{- range $i, $value := .EnvVars }}{{- if $i }} +
+:is-deprecated: {{ .IsDeprecated }}
+| {{- range $i, $value := .EnvVars }}{{- if $i }} + |
 {{ end -}}
 `{{- $value }}`
-{{- end }}
+{{- end }} +
+ifeval::[{is-deprecated} == true] 
+xref:deprecation-note[Deprecation Note] 
+endif::[] 
 a| [subs=-attributes]
 ++{{.Type}} ++
 a| [subs=-attributes]
@@ -20,6 +46,5 @@ a| [subs=-attributes]
 {{.Description}}
 
 {{- end }}
-|===
+| === |
 
-Since Version: `+` added, `-` deprecated