From b88b1946d2d4d84807f42b41768f1628658a0fad Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Tue, 3 May 2022 15:18:24 +0200 Subject: [PATCH 1/3] add initial adoc export Signed-off-by: Christian Richter --- docs/extensions/_includes/.gitignore | 3 +- docs/extensions/_includes/adoc/.gitkeep | 0 docs/helpers/adoc-generator.go.tmpl | 94 +++++++++++++++++++++++++ docs/helpers/configenvextractor.go | 1 + docs/templates/ADOC.tmpl | 19 +++++ 5 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 docs/extensions/_includes/adoc/.gitkeep create mode 100644 docs/helpers/adoc-generator.go.tmpl create mode 100644 docs/templates/ADOC.tmpl diff --git a/docs/extensions/_includes/.gitignore b/docs/extensions/_includes/.gitignore index 3b7434f1055..02c62065646 100644 --- a/docs/extensions/_includes/.gitignore +++ b/docs/extensions/_includes/.gitignore @@ -1,2 +1,3 @@ *_configvars.md -*-example.yaml \ No newline at end of file +*-example.yaml +adoc/*adoc \ No newline at end of file diff --git a/docs/extensions/_includes/adoc/.gitkeep b/docs/extensions/_includes/adoc/.gitkeep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl new file mode 100644 index 00000000000..d9e1cb24337 --- /dev/null +++ b/docs/helpers/adoc-generator.go.tmpl @@ -0,0 +1,94 @@ +package main + +import ( + "fmt" + "io/ioutil" + "log" + "os" + "path/filepath" + "reflect" + "strings" + "text/template" + + {{- range $key, $value := .}} + pkg{{$key}} "{{$value}}" + {{- end}}) + +type ConfigField struct { + Name string + DefaultValue string + Type string + Description string + VersionInfo string +} + +func main() { +fmt.Println("Generating adoc documentation for environment variables:") +content, err := ioutil.ReadFile("../../docs/templates/ADOC.tmpl") +if err != nil { + log.Fatal(err) +} +replacer := strings.NewReplacer( + "github.com/owncloud/ocis/extensions/", "", + "/pkg/config/defaults", "", + ) +var fields []ConfigField +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/extensions/_includes/adoc/" + for pkg, conf := range m { + fields = GetAnnotatedVariables(conf) + if len(fields) > 0 { + fmt.Printf("... %s\n", pkg) + targetFile, err = os.Create(filepath.Join(targetFolder, replacer.Replace(pkg) + "_configvars.adoc")) + if err != nil { + log.Fatalf("Failed to create target file: %s", err) + } + defer targetFile.Close() + if err := tpl.Execute(targetFile, fields); err != nil { + log.Fatalf("Failed to execute template: %s", err) + } + } + } + fmt.Println("done") +} + +func GetAnnotatedVariables(s interface{}) []ConfigField { + t := reflect.TypeOf(s) + v := reflect.ValueOf(s) + + var fields []ConfigField + for i := 0; i < t.NumField(); i++ { + field := t.Field(i) + value := v.Field(i) + + switch value.Kind() { + default: + desc := field.Tag.Get("desc") + env, ok := field.Tag.Lookup("env") + if !ok { + continue + } + v := fmt.Sprintf("%v", value.Interface()) + fields = append(fields, ConfigField{Name: strings.ReplaceAll(env, ";", " +\n"), DefaultValue: v, Description: desc, Type: value.Type().Name()}) + 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())...) + } + case reflect.Struct: + fields = append(fields, GetAnnotatedVariables(value.Interface())...) + } + } + return fields +} diff --git a/docs/helpers/configenvextractor.go b/docs/helpers/configenvextractor.go index d7afd529553..6b49f9dc1ab 100644 --- a/docs/helpers/configenvextractor.go +++ b/docs/helpers/configenvextractor.go @@ -13,6 +13,7 @@ import ( ) var targets = map[string]string{ + "adoc-generator.go.tmpl": "output/adoc/adoc-generator.go", "example-config-generator.go.tmpl": "output/exampleconfig/example-config-generator.go", "extractor.go.tmpl": "output/env/runner.go", } diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl new file mode 100644 index 00000000000..512248b6b20 --- /dev/null +++ b/docs/templates/ADOC.tmpl @@ -0,0 +1,19 @@ +[caption=] +.Environment variables for the frontend extension +[width="100%",cols="~,~,~,~",options="header"] +|=== +| Name +| Type +| Default Value +| Description + +{{- range .}} +| `{{.Name}}` +| {{.Type}} +| {{.DefaultValue}} +| {{.Description}} + +{{- end }} +|=== + +Since Version: `+` added, `-` deprecated From 4e0e19dfc7d4a6db4d036c76cf36b70e29736589 Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Wed, 4 May 2022 12:22:13 +0200 Subject: [PATCH 2/3] add extension name to adoc template Signed-off-by: Christian Richter --- docs/helpers/adoc-generator.go.tmpl | 12 +++++++++++- docs/templates/ADOC.tmpl | 4 ++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/helpers/adoc-generator.go.tmpl b/docs/helpers/adoc-generator.go.tmpl index d9e1cb24337..8f63a391b25 100644 --- a/docs/helpers/adoc-generator.go.tmpl +++ b/docs/helpers/adoc-generator.go.tmpl @@ -22,6 +22,11 @@ type ConfigField struct { VersionInfo string } +type templateData struct { + ExtensionName string + Fields []ConfigField +} + func main() { fmt.Println("Generating adoc documentation for environment variables:") content, err := ioutil.ReadFile("../../docs/templates/ADOC.tmpl") @@ -52,7 +57,12 @@ m := map[string]interface{}{ log.Fatalf("Failed to create target file: %s", err) } defer targetFile.Close() - if err := tpl.Execute(targetFile, fields); err != nil { + + td := templateData{ + ExtensionName: replacer.Replace(pkg), + Fields: fields, + } + if err := tpl.Execute(targetFile, td); err != nil { log.Fatalf("Failed to execute template: %s", err) } } diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl index 512248b6b20..4c01386ddba 100644 --- a/docs/templates/ADOC.tmpl +++ b/docs/templates/ADOC.tmpl @@ -1,5 +1,5 @@ [caption=] -.Environment variables for the frontend extension +.Environment variables for the {{ .ExtensionName }} extension [width="100%",cols="~,~,~,~",options="header"] |=== | Name @@ -7,7 +7,7 @@ | Default Value | Description -{{- range .}} +{{- range .Fields}} | `{{.Name}}` | {{.Type}} | {{.DefaultValue}} From 9d7c9d34093d46051dd1ab9e326242cd16eef9cc Mon Sep 17 00:00:00 2001 From: Christian Richter Date: Wed, 4 May 2022 12:22:26 +0200 Subject: [PATCH 3/3] add yaml filename to example yaml Signed-off-by: Christian Richter --- docs/helpers/example-config-generator.go.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/helpers/example-config-generator.go.tmpl b/docs/helpers/example-config-generator.go.tmpl index 277cfdc9dc2..5e883d4b81a 100644 --- a/docs/helpers/example-config-generator.go.tmpl +++ b/docs/helpers/example-config-generator.go.tmpl @@ -27,7 +27,7 @@ func main() { if err != nil { log.Fatalf("Marshalling yaml for pkg0 failed: %s\n", err) } - return "# Autogenerated\n" + string(yml) + return fmt.Sprintf("# Autogenerated\n# Filename: %s-config-example.yaml\n\n%s", replacer.Replace("{{ $value }}"),string(yml)) }(), {{- end}} }