Merge pull request #3078 from owncloud/config-docs

generate environment variable config documentation
2022-03-02 16:15:37 +01:00
parent beaac40aa6 d5aed899e7
commit 44db94cbe7
43 changed files with 402 additions and 40 deletions
@@ -1260,7 +1260,7 @@ def docs(ctx):
            {
                "name": "docs-generate",
                "image": OC_CI_GOLANG,
-                "commands": ["make -C %s docs-generate" % (module) for module in config["modules"]],
+                "commands": ["make -C docs docs-generate"],
            },
            {
                "name": "prepare",
@@ -25,45 +25,45 @@ type Config struct {
 	Repo               Repo        `ocisConfig:"repo"`
 	Index              Index       `ocisConfig:"index"`
 	ServiceUser        ServiceUser `ocisConfig:"service_user"`
-	HashDifficulty     int         `ocisConfig:"hash_difficulty" env:"ACCOUNTS_HASH_DIFFICULTY"`
-	DemoUsersAndGroups bool        `ocisConfig:"demo_users_and_groups" env:"ACCOUNTS_DEMO_USERS_AND_GROUPS"`
+	HashDifficulty     int         `ocisConfig:"hash_difficulty" env:"ACCOUNTS_HASH_DIFFICULTY" desc:"The hash difficulty makes sure that validating a password takes at least a certain amount of time."`
+	DemoUsersAndGroups bool        `ocisConfig:"demo_users_and_groups" env:"ACCOUNTS_DEMO_USERS_AND_GROUPS" desc:"If this flag is set the service will setup the demo users and groups."`

 	Context context.Context
 }

 // Asset defines the available asset configuration.
 type Asset struct {
-	Path string `ocisConfig:"path" env:"ACCOUNTS_ASSET_PATH"`
+	Path string `ocisConfig:"path" env:"ACCOUNTS_ASSET_PATH" desc:"The path to the ui assets."`
 }

 // TokenManager is the config for using the reva token manager
 type TokenManager struct {
-	JWTSecret string `ocisConfig:"jwt_secret" env:"OCIS_JWT_SECRET;ACCOUNTS_JWT_SECRET"`
+	JWTSecret string `ocisConfig:"jwt_secret" env:"OCIS_JWT_SECRET;ACCOUNTS_JWT_SECRET" desc:"The secret to mint jwt tokens."`
 }

 // Repo defines which storage implementation is to be used.
 type Repo struct {
-	Backend string `ocisConfig:"backend"  env:"ACCOUNTS_STORAGE_BACKEND"`
+	Backend string `ocisConfig:"backend" env:"ACCOUNTS_STORAGE_BACKEND" desc:"Defines which storage implementation is to be used"`
 	Disk    Disk   `ocisConfig:"disk"`
 	CS3     CS3    `ocisConfig:"cs3"`
 }

 // Disk is the local disk implementation of the storage.
 type Disk struct {
-	Path string `ocisConfig:"path" env:"ACCOUNTS_STORAGE_DISK_PATH"`
+	Path string `ocisConfig:"path" env:"ACCOUNTS_STORAGE_DISK_PATH" desc:"The path where the accounts data is stored."`
 }

 // CS3 is the cs3 implementation of the storage.
 type CS3 struct {
-	ProviderAddr string `ocisConfig:"provider_addr" env:"ACCOUNTS_STORAGE_CS3_PROVIDER_ADDR"`
+	ProviderAddr string `ocisConfig:"provider_addr" env:"ACCOUNTS_STORAGE_CS3_PROVIDER_ADDR" desc:"The address to the storage provider."`
 }

 // ServiceUser defines the user required for EOS.
 type ServiceUser struct {
-	UUID     string `ocisConfig:"uuid" env:"ACCOUNTS_SERVICE_USER_UUID"`
-	Username string `ocisConfig:"username" env:"ACCOUNTS_SERVICE_USER_USERNAME"`
-	UID      int64  `ocisConfig:"uid" env:"ACCOUNTS_SERVICE_USER_UID"`
-	GID      int64  `ocisConfig:"gid" env:"ACCOUNTS_SERVICE_USER_GID"`
+	UUID     string `ocisConfig:"uuid" env:"ACCOUNTS_SERVICE_USER_UUID" desc:"The id of the accounts service user."`
+	Username string `ocisConfig:"username" env:"ACCOUNTS_SERVICE_USER_USERNAME" desc:"The username of the accounts service user."`
+	UID      int64  `ocisConfig:"uid" env:"ACCOUNTS_SERVICE_USER_UID" desc:"The uid of the accounts service user."`
+	GID      int64  `ocisConfig:"gid" env:"ACCOUNTS_SERVICE_USER_GID" desc:"The gid of the accounts service user."`
 }

 // Index defines config for indexes.
@@ -74,12 +74,12 @@ type Index struct {

 // GIDBound defines a lower and upper bound.
 type GIDBound struct {
-	Lower int64 `ocisConfig:"lower" env:"ACCOUNTS_GID_INDEX_LOWER_BOUND"`
-	Upper int64 `ocisConfig:"upper" env:"ACCOUNTS_GID_INDEX_UPPER_BOUND"`
+	Lower int64 `ocisConfig:"lower" env:"ACCOUNTS_GID_INDEX_LOWER_BOUND" desc:"The lowest possible gid value for the indexer."`
+	Upper int64 `ocisConfig:"upper" env:"ACCOUNTS_GID_INDEX_UPPER_BOUND" desc:"The highest possible gid value for the indexer."`
 }

 // UIDBound defines a lower and upper bound.
 type UIDBound struct {
-	Lower int64 `ocisConfig:"lower" env:"ACCOUNTS_UID_INDEX_LOWER_BOUND"`
-	Upper int64 `ocisConfig:"upper" env:"ACCOUNTS_UID_INDEX_UPPER_BOUND"`
+	Lower int64 `ocisConfig:"lower" env:"ACCOUNTS_UID_INDEX_LOWER_BOUND" desc:"The lowest possible uid value for the indexer."`
+	Upper int64 `ocisConfig:"upper" env:"ACCOUNTS_UID_INDEX_UPPER_BOUND" desc:"The highest possible uid value for the indexer."`
 }
@@ -2,6 +2,6 @@ package config

 // GRPC defines the available grpc configuration.
 type GRPC struct {
-	Addr      string `ocisConfig:"addr" env:"ACCOUNTS_GRPC_ADDR"`
+	Addr      string `ocisConfig:"addr" env:"ACCOUNTS_GRPC_ADDR" desc:"The address of the grpc service."`
 	Namespace string
 }
@@ -2,11 +2,11 @@ package config

 // HTTP defines the available http configuration.
 type HTTP struct {
-	Addr      string `ocisConfig:"addr" env:"ACCOUNTS_HTTP_ADDR"`
+	Addr      string `ocisConfig:"addr" env:"ACCOUNTS_HTTP_ADDR" desc:"The address of the http service."`
 	Namespace string
-	Root      string `ocisConfig:"root" env:"ACCOUNTS_HTTP_ROOT"`
-	CacheTTL  int    `ocisConfig:"cache_ttl" env:"ACCOUNTS_CACHE_TTL"`
-	CORS      CORS   `ocisConfig:"cors"`
+	Root      string `ocisConfig:"root" env:"ACCOUNTS_HTTP_ROOT" desc:"The root path of the http service."`
+	CacheTTL  int    `ocisConfig:"cache_ttl" env:"ACCOUNTS_CACHE_TTL" desc:"The cache time for the static assets."`
+	CORS      CORS
 }

 // CORS defines the available cors configuration.
@@ -2,8 +2,8 @@ package config

 // Log defines the available log configuration.
 type Log struct {
-	Level  string `mapstructure:"level" env:"OCIS_LOG_LEVEL;ACCOUNTS_LOG_LEVEL"`
-	Pretty bool   `mapstructure:"pretty" env:"OCIS_LOG_PRETTY;ACCOUNTS_LOG_PRETTY"`
-	Color  bool   `mapstructure:"color" env:"OCIS_LOG_COLOR;ACCOUNTS_LOG_COLOR"`
-	File   string `mapstructure:"file" env:"OCIS_LOG_FILE;ACCOUNTS_LOG_FILE"`
+	Level  string `ocisConfig:"level" env:"OCIS_LOG_LEVEL;ACCOUNTS_LOG_LEVEL" desc:"The log level."`
+	Pretty bool   `ocisConfig:"pretty" env:"OCIS_LOG_PRETTY;ACCOUNTS_LOG_PRETTY" desc:"Activates pretty log output."`
+	Color  bool   `ocisConfig:"color" env:"OCIS_LOG_COLOR;ACCOUNTS_LOG_COLOR" desc:"Activates colorized log output."`
+	File   string `ocisConfig:"file" env:"OCIS_LOG_FILE;ACCOUNTS_LOG_FILE" desc:"The target log file."`
 }
@@ -2,8 +2,8 @@ package config

 // Tracing defines the available tracing configuration.
 type Tracing struct {
-	Enabled   bool   `ocisConfig:"enabled" env:"OCIS_TRACING_ENABLED;ACCOUNTS_TRACING_ENABLED"`
+	Enabled   bool   `ocisConfig:"enabled" env:"OCIS_TRACING_ENABLED;ACCOUNTS_TRACING_ENABLED" desc:"Activates tracing."`
 	Type      string `ocisConfig:"type" env:"OCIS_TRACING_TYPE;ACCOUNTS_TRACING_TYPE"`
-	Endpoint  string `ocisConfig:"endpoint" env:"OCIS_TRACING_ENDPOINT;ACCOUNTS_TRACING_ENDPOINT"`
+	Endpoint  string `ocisConfig:"endpoint" env:"OCIS_TRACING_ENDPOINT;ACCOUNTS_TRACING_ENDPOINT" desc:"The endpoint to the tracing collector."`
 	Collector string `ocisConfig:"collector" env:"OCIS_TRACING_COLLECTOR;ACCOUNTS_TRACING_COLLECTOR"`
 }
@@ -8,6 +8,7 @@ help:

 .PHONY: docs-generate
 docs-generate: ## run docs-generate for all oCIS extensions
+	@pushd helpers && go run configenvextractor.go; popd
 	@$(MAKE) --no-print-directory -C ../ docs-generate

 .PHONY: docs-init
@@ -0,0 +1 @@
+*_configvars.md
@@ -0,0 +1,3 @@
+---
+GeekdocHidden: true
+---
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/accounts
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/accounts_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/glauth
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/glauth_configvars.md" >}}
@@ -1 +0,0 @@
-configuration.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/graph-explorer
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/graph-explorer_configvars.md" >}}
@@ -1 +0,0 @@
-configuration.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/graph
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/graph_configvars.md" >}}
@@ -0,0 +1,16 @@
+---
+title: IDM
+date: 2022-03-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/idm
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+## Abstract
+
+
+## Table of Contents
+
+{{< toc-tree >}}
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/idm
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/idm_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/idp
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/idp_configvars.md" >}}
@@ -0,0 +1,16 @@
+---
+title: NATS
+date: 2022-03-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/nats
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+## Abstract
+
+
+## Table of Contents
+
+{{< toc-tree >}}
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/nats
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/nats_configvars.md" >}}
@@ -0,0 +1,16 @@
+---
+title: Notifications
+date: 2022-03-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/notifications
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+## Abstract
+
+
+## Table of Contents
+
+{{< toc-tree >}}
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/notifications
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/notifications_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/ocs
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/ocs_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/proxy
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/proxy_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/settings
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/settings_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/store
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/store_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/thumbnails
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/thumbnails_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/web
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/web_configvars.md" >}}
@@ -1,2 +1 @@
-configuration.md
 grpc.md
@@ -0,0 +1,12 @@
+---
+title: Service Configuration
+date: 2018-05-02T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/webdav
+geekdocFilePath: configuration.md
+geekdocCollapseSection: true
+---
+
+
+{{< include file="extensions/_includes/webdav_configvars.md" >}}
@@ -0,0 +1,50 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"text/template"
+)
+
+func main() {
+	fmt.Println("Getting relevant packages")
+	paths, err := filepath.Glob("../../*/pkg/config/defaultconfig.go")
+	if err != nil {
+		log.Fatal(err)
+	}
+	replacer := strings.NewReplacer(
+		"../../", "github.com/owncloud/ocis/",
+		"/defaultconfig.go", "",
+	)
+	for i := range paths {
+		paths[i] = replacer.Replace(paths[i])
+	}
+	content, err := ioutil.ReadFile("extractor.go.tmpl")
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println("Generating intermediate go code")
+	tpl := template.Must(template.New("").Parse(string(content)))
+	os.Mkdir("output", 0700)
+	runner, err := os.Create("output/runner.go")
+	if err != nil {
+		log.Fatal(err)
+	}
+	tpl.Execute(runner, paths)
+	fmt.Println("Running intermediate go code")
+	os.Chdir("output")
+	os.Setenv("OCIS_BASE_DATA_PATH", "~/.ocis")
+	out, err := exec.Command("go", "run", "runner.go").Output()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(string(out))
+	fmt.Println("Cleaning up")
+	os.Chdir("../")
+	os.RemoveAll("output")
+}
@@ -0,0 +1,85 @@
+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
+}
+
+func main() {
+fmt.Println("Generating documentation for environment variables:")
+content, err := ioutil.ReadFile("../../../docs/templates/CONFIGURATION.tmpl")
+if err != nil {
+    log.Fatal(err)
+}
+replacer := strings.NewReplacer(
+		"github.com/owncloud/ocis/", "",
+		"/pkg/config", "",
+	)
+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}}.DefaultConfig(),
+{{- end }}
+}
+
+    targetFolder := "../../../docs/extensions/_includes/"
+    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.md"))
+		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: env, DefaultValue: v, Description: desc, Type: value.Type().Name()})
+		case reflect.Struct:
+			fields = append(fields, GetAnnotatedVariables(value.Interface())...)
+		}
+	}
+	return fields
+}
@@ -0,0 +1,7 @@
+## Environment Variables
+
+| Name | Type | Default Value | Description |
+|------|------|---------------|-------------|
+{{- range .}}
+| {{.Name}} | {{.Type}} | {{.DefaultValue}} | {{.Description}}|
+{{- end }}