From ca300c966e2875c66a25011f78c71a9aabad2c52 Mon Sep 17 00:00:00 2001 From: jkoberg Date: Tue, 10 Jan 2023 12:40:09 +0100 Subject: [PATCH 1/3] collect global envvars Signed-off-by: jkoberg --- docs/helpers/adoc-generator.go.tmpl | 120 +++++++++++++++++++++------- docs/templates/ADOC_global.tmpl | 30 +++++++ 2 files changed, 120 insertions(+), 30 deletions(-) create mode 100644 docs/templates/ADOC_global.tmpl diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl index 0ed23f86e5..a66300f1fa 100644 --- a/docs/helpers/adoc-generator.go.tmpl +++ b/docs/helpers/adoc-generator.go.tmpl @@ -14,6 +14,7 @@ import ( pkg{{$key}} "{{$value}}" {{- end}}) +// ConfigField is the representation of one configuration field type ConfigField struct { EnvVars []string DefaultValue string @@ -23,6 +24,7 @@ type ConfigField struct { DeprecationLink string } +// DeprecationField holds information about deprecation type DeprecationField struct { DeprecationVersion string DeprecationInfo string @@ -30,6 +32,15 @@ type DeprecationField struct { RemovalVersion string } +// EnvVar holds information about one envvar +type EnvVar struct { + Name string + DefaultValue string + Type string + Description string + Services []string +} + type templateData struct { ExtensionName string Fields []ConfigField @@ -38,44 +49,63 @@ type templateData struct { } func main() { -fmt.Println("Generating adoc documentation for environment variables:") -content, err := os.ReadFile("../../docs/templates/ADOC.tmpl") -if err != nil { - log.Fatal(err) -} -replacer := strings.NewReplacer( - "github.com/owncloud/ocis/v2/services/", "", - "/pkg/config/defaults", "", - ) -var fields []ConfigField -var deprecations []DeprecationField -var targetFile *os.File -tpl := template.Must(template.New("").Parse(string(content))) + fmt.Println("Generating adoc documentation for environment variables:") + content, err := os.ReadFile("../../docs/templates/ADOC.tmpl") + if err != nil { + log.Fatal(err) + } + replacer := strings.NewReplacer( + "github.com/owncloud/ocis/v2/services/", "", + "/pkg/config/defaults", "", + ) + var fields []ConfigField + var deprecations []DeprecationField + var targetFile *os.File + tpl := template.Must(template.New("").Parse(string(content))) -m := map[string]interface{}{ -{{- range $key, $value := .}} - "{{$value}}": *pkg{{$key}}.FullDefaultConfig(), -{{- end }} -} - - targetFolder := "../../docs/services/_includes/adoc/" - for pkg, conf := range m { - fields, deprecations = GetAnnotatedVariables(conf) - var hasDeprecations bool - if len(deprecations) > 0 { - hasDeprecations = true + m := map[string]interface{}{ + {{- range $key, $value := .}} + "{{$value}}": *pkg{{$key}}.FullDefaultConfig(), + {{- end }} } - if len(fields) > 0 || len(deprecations) > 0 { - fmt.Printf("... %s\n", pkg) - targetFile, err = os.Create(filepath.Join(targetFolder, replacer.Replace(pkg) + "_configvars.adoc")) + targetFolder := "../../docs/services/_includes/adoc/" + all := make(map[string]EnvVar) + for pkg, conf := range m { + service := replacer.Replace(pkg) + fields, deprecations = GetAnnotatedVariables(conf) + var hasDeprecations bool + if len(deprecations) > 0 { + hasDeprecations = true + } + + for _, f := range fields { + for _, e := range f.EnvVars { + if env, ok := all[e]; ok { + env.Services = append(env.Services, service) + all[e] = env + } else { + all[e] = EnvVar{ + Name: e, + Description: f.Description, + Type: f.Type, + DefaultValue: f.DefaultValue, + Services: []string{service}, + } + } + } + } + + if len(fields) > 0 || len(deprecations) > 0 { + fmt.Printf("... %s\n", pkg) + targetFile, err = os.Create(filepath.Join(targetFolder, service + "_configvars.adoc")) if err != nil { log.Fatalf("Failed to create target file: %s", err) } defer targetFile.Close() td := templateData{ - ExtensionName: replacer.Replace(pkg), + ExtensionName: service, Fields: fields, Deprecations: deprecations, HasDeprecations: hasDeprecations , @@ -83,8 +113,38 @@ m := map[string]interface{}{ if err := tpl.Execute(targetFile, td); err != nil { log.Fatalf("Failed to execute template: %s", err) } + } } - } + + // render global env vars + tmplValues := make([]map[string]interface{}, 0) + for _, env := range all { + if len(env.Services) > 1 { + tmplValues = append(tmplValues, map[string]interface{}{ + "Name": env.Name, + "Services": env.Services, + "Description": env.Description, + "DefaultValue": env.DefaultValue, + "Type": env.Type, + }) + } + } + + glc, err := os.ReadFile("../../docs/templates/ADOC_global.tmpl") + if err != nil { + log.Fatal(err) + } + + gltpl := template.Must(template.New("").Parse(string(glc))) + glfile, err := os.Create(filepath.Join(targetFolder, "global_configvars.adoc")) + if err != nil { + log.Fatalf("Failed to create target file: %s", err) + } + + if err := gltpl.Execute(glfile, tmplValues); err != nil { + log.Printf("Failed to execute template: %s", err) + } + fmt.Println("done") } diff --git a/docs/templates/ADOC_global.tmpl b/docs/templates/ADOC_global.tmpl new file mode 100644 index 0000000000..aaaae12e0f --- /dev/null +++ b/docs/templates/ADOC_global.tmpl @@ -0,0 +1,30 @@ +[caption=] +.Environment variables with global scope available in multiple services +[width="100%",cols="~,~,~,~,~",options="header"] +|=== +| Name +| Services +| Type +| Default Value +| Description + +{{ range . }} + +a| `{{ .Name }}` + +a| [subs=-attributes] +{{- range .Services}} +xref:{s-path}/{{ . }}.adoc[{{ . }}] + +{{- end }} + +a| [subs=-attributes] +++{{ .Type }} ++ + +a| [subs=-attributes] +++{{ .DefaultValue }} ++ + +a| [subs=-attributes] +++{{ .Description }} ++ + +{{- end }} +|=== From bb9c65db7b53657e8f7edc6e8aee226ca624fda8 Mon Sep 17 00:00:00 2001 From: jkoberg Date: Tue, 10 Jan 2023 12:41:58 +0100 Subject: [PATCH 2/3] changelog Signed-off-by: jkoberg --- changelog/unreleased/collect-global-envvars.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog/unreleased/collect-global-envvars.md diff --git a/changelog/unreleased/collect-global-envvars.md b/changelog/unreleased/collect-global-envvars.md new file mode 100644 index 0000000000..7dd08f6889 --- /dev/null +++ b/changelog/unreleased/collect-global-envvars.md @@ -0,0 +1,5 @@ +Enhancement: Collect global envvars + +Compose a list of all envvars living in more than 1 service + +https://github.com/owncloud/ocis/pull/5367 From a3bcb80fe3bf5b179000acc06511b95822ca8498 Mon Sep 17 00:00:00 2001 From: jkoberg Date: Tue, 10 Jan 2023 14:43:18 +0100 Subject: [PATCH 3/3] improve template and sort results Signed-off-by: jkoberg --- docs/helpers/adoc-generator.go.tmpl | 12 +++++++++++- docs/templates/ADOC_global.tmpl | 11 +++++++---- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl index a66300f1fa..977363ad15 100644 --- a/docs/helpers/adoc-generator.go.tmpl +++ b/docs/helpers/adoc-generator.go.tmpl @@ -9,10 +9,12 @@ import ( "regexp" "strings" "text/template" + "sort" {{- range $key, $value := .}} pkg{{$key}} "{{$value}}" - {{- end}}) + {{- end}} +) // ConfigField is the representation of one configuration field type ConfigField struct { @@ -83,6 +85,9 @@ func main() { for _, e := range f.EnvVars { if env, ok := all[e]; ok { env.Services = append(env.Services, service) + sort.Slice(env.Services, func(i, j int) bool { + return env.Services[i] < env.Services[j] + }) all[e] = env } else { all[e] = EnvVar{ @@ -130,6 +135,11 @@ func main() { } } + // sort + sort.Slice(tmplValues, func(i, j int) bool { + return tmplValues[i]["Name"].(string) < tmplValues[j]["Name"].(string) + }) + glc, err := os.ReadFile("../../docs/templates/ADOC_global.tmpl") if err != nil { log.Fatal(err) diff --git a/docs/templates/ADOC_global.tmpl b/docs/templates/ADOC_global.tmpl index aaaae12e0f..cbc43b850c 100644 --- a/docs/templates/ADOC_global.tmpl +++ b/docs/templates/ADOC_global.tmpl @@ -1,6 +1,9 @@ +// collected through docs/helpers/adoc-generator.go.tmpl + +[.landscape] [caption=] .Environment variables with global scope available in multiple services -[width="100%",cols="~,~,~,~,~",options="header"] +[width="100%",cols="30%,25%,~,~,~",options="header"] |=== | Name | Services @@ -12,9 +15,9 @@ a| `{{ .Name }}` -a| [subs=-attributes] +a| [subs=attributes+] {{- range .Services}} -xref:{s-path}/{{ . }}.adoc[{{ . }}] + +* xref:{s-path}/{{ . }}.adoc[{{ . }}] + {{- end }} a| [subs=-attributes] @@ -24,7 +27,7 @@ a| [subs=-attributes] ++{{ .DefaultValue }} ++ a| [subs=-attributes] -++{{ .Description }} ++ +{{ .Description }} {{- end }} |===