add more config doc descriptions

changelog/unreleased/fix-remove-unused-config-options.md

@@ -0,0 +1,12 @@
+Bugfix: Remove unused configuration options
+
+We've removed multiple unused configuration options:
+
+- `STORAGE_SYSTEM_DATAPROVIDER_INSECURE`, see also cs3org/reva#2993
+- `STORAGE_USERS_DATAPROVIDER_INSECURE`, see also cs3org/reva#2993
+- `STORAGE_SYSTEM_TEMP_FOLDER`, see also cs3org/reva#2993 
+- `STORAGE_USERS_TEMP_FOLDER`, see also cs3org/reva#2993
+- `WEB_UI_CONFIG_VERSION`, see also owncloud/web#7130
+
+https://github.com/owncloud/ocis/pull/3973
+

docs/extensions/graph-explorer/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
+
 This service embeds [Graph-Explorer](https://github.com/owncloud/ocis/tree/master/graph-explorer) to provide a UI for ownCloud Infinite Scale.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/graph/_index.md

@@ -8,6 +8,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides a simple graph world API which can be used by clients or other extensions.
 
+## Table of Contents
+
 {{< toc-tree >}}

docs/extensions/idp/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides an OpenID Connect provider which is the default way to authenticate in oCIS.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/ocs/_index.md

@@ -8,4 +8,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides the OCS API which is required by some ownCloud clients.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/proxy/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides a proxy service that routes requests to the correct extensions.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/search/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides search functionality.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/settings/_index.md

@@ -45,3 +45,7 @@ The forms are generated from the registered *settings bundles*.
 if it's available. The SDK uses sensible defaults when ocis-settings is not part of the setup.
 
 For compatibility with ownCloud 10, a migration of ownCloud 10 settings into the storage of ocis-settings will be available.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/sharing/_index.md

@@ -7,4 +7,10 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides sharing functionality.
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/store/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides ...
+
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/thumbnails/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides an ocis extensions which generates thumbnails for image files.
+
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/web/_index.md

@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service embeds [ownCloud Web](https://github.com/owncloud/web) to provide a UI for ownCloud Infinite Scale.
+
+
+## Table of Contents
+
+{{< toc-tree >}}

docs/extensions/webdav/_index.md

@@ -1,5 +1,5 @@
 ---
-title: WebDaV
+title: WebDAV
 date: 2018-05-02T00:00:00+00:00
 weight: 20
 geekdocRepo: https://github.com/owncloud/ocis
@@ -8,4 +8,11 @@ geekdocFilePath: _index.md
 geekdocCollapseSection: true
 ---
 
+## Abstract
+
 This service provides the WebDAV API which is required by some ownCloud clients.
+
+
+## Table of Contents
+
+{{< toc-tree >}}

extensions/app-provider/pkg/config/config.go

@@ -52,7 +52,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"APP_PROVIDER_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"APP_PROVIDER_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"APP_PROVIDER_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/app-registry/pkg/config/config.go

@@ -50,7 +50,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"APP_REGISTRY_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"APP_REGISTRY_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"APP_REGISTRY_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/auth-basic/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BASIC_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's groupmember ships in the reva access token. To reduces token size, especially when users are members of a large number of groups."`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BASIC_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups."`
  AuthProvider string `yaml:"auth_provider" env:"AUTH_BASIC_AUTH_PROVIDER" desc:"The auth provider which should be used by the service (e.g. 'ldap')."`
  AuthProviders AuthProviders `yaml:"auth_providers"`
 
@@ -51,7 +51,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"AUTH_BASIC_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"AUTH_BASIC_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"AUTH_BASIC_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/auth-bearer/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN" desc:"Skip storing all groups of a user in the jwt token."`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups."`
 
  OIDC OIDC `yaml:"oidc"`
 
@@ -51,7 +51,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"AUTH_BEARER_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"AUTH_BEARER_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"AUTH_BEARER_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/auth-machine/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN" desc:"Skip storing all groups of a user in the jwt token."`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups."`
 
  MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;AUTH_MACHINE_API_KEY" desc:"Machine auth API key used for validating requests from other services when impersonating users."`
 
@@ -51,7 +51,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"AUTH_MACHINE_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"AUTH_MACHINE_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"AUTH_MACHINE_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/frontend/pkg/config/config.go

@@ -17,13 +17,13 @@ type Config struct {
 
  // JWTSecret used to verify reva access token
 
- TransferSecret string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET"`
+ TransferSecret string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET" desc:"Transfer secret for signing file up- and download requests."`
 
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
- MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;FRONTEND_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service."`
+ MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;FRONTEND_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"FRONTEND_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces token size, especially when users are members of a large number of groups."`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"FRONTEND_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the loading of user's group memberships from the reva access token."`
 
  EnableFavorites bool `yaml:"enable_favorites" env:"FRONTEND_ENABLE_FAVORITES" desc:"Disables the support for favorites in the frontend."`
  EnableProjectSpaces bool `yaml:"enable_project_spaces" env:"FRONTEND_ENABLE_PROJECT_SPACES" desc:"Indicates to clients that project spaces are supposed to be made available."`
@@ -71,7 +71,7 @@ type Debug struct {
 }
 
 type HTTPConfig struct {
- Addr string `yaml:"addr" env:"FRONTEND_HTTP_ADDR" desc:"The address of the http service."`
+ Addr string `yaml:"addr" env:"FRONTEND_HTTP_ADDR" desc:"The bind address of the HTTP service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"FRONTEND_HTTP_PROTOCOL" desc:"The transport protocol of the http service."`
  Prefix string `yaml:"prefix" env:"FRONTEND_HTTP_PREFIX" desc:"The Path prefix where the frontend can be accessed (defaults to /)."`

extensions/gateway/pkg/config/config.go

@@ -19,18 +19,18 @@ type Config struct {
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"GATEWAY_SKIP_USER_GROUPS_IN_TOKEN"`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"GATEWAY_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the loading of user's group memberships from the reva access token."`
 
  CommitShareToStorageGrant bool `yaml:"commit_share_to_storage_grant" env:"GATEWAY_COMMIT_SHARE_TO_STORAGE_GRANT"`
  CommitShareToStorageRef bool `yaml:"commit_share_to_storage_ref" env:"GATEWAY_COMMIT_SHARE_TO_STORAGE_REF"`
  ShareFolder string `yaml:"share_folder_name" env:"GATEWAY_SHARE_FOLDER_NAME"`
  DisableHomeCreationOnLogin bool `yaml:"disable_home_creation_on_login" env:"GATEWAY_DISABLE_HOME_CREATION_ON_LOGIN"`
- TransferSecret string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET"` // TODO: how to name the env
+ TransferSecret string `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET" desc:"Transfer secret for signing file up- and download requests."`
  TransferExpires int `yaml:"transfer_expires" env:"GATEWAY_TRANSFER_EXPIRES"`
  HomeMapping string `yaml:"home_mapping" env:"GATEWAY_HOME_MAPPING"`
  EtagCacheTTL int `yaml:"etag_cache_ttl" env:"GATEWAY_ETAG_CACHE_TTL"`
 
- FrontendPublicURL string `yaml:"frontend_public_url" env:"OCIS_URL;GATEWAY_FRONTEND_PUBLIC_URL"`
+ FrontendPublicURL string `yaml:"frontend_public_url" env:"OCIS_URL;GATEWAY_FRONTEND_PUBLIC_URL" desc:"URL, where oCIS is reachable for users."`
 
  UsersEndpoint string `yaml:"users_endpoint" env:"GATEWAY_USERS_ENDPOINT"`
  GroupsEndpoint string `yaml:"groups_endpoint" env:"GATEWAY_GROUPS_ENDPOINT"`
@@ -75,7 +75,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"GATEWAY_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"GATEWAY_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"GATEWAY_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/graph-explorer/pkg/config/http.go

@@ -2,8 +2,8 @@ package config
 
 // HTTP defines the available http configuration.
 type HTTP struct {
- Addr string `yaml:"addr" env:"GRAPH_EXPLORER_HTTP_ADDR" desc:"The HTTP service address."`
- Root string `yaml:"root" env:"GRAPH_EXPLORER_HTTP_ROOT" desc:"The HTTP service root path."`
+ Addr string `yaml:"addr" env:"GRAPH_EXPLORER_HTTP_ADDR" desc:"The bind address of the HTTP service."`
+ Root string `yaml:"root" env:"GRAPH_EXPLORER_HTTP_ROOT" desc:"The root path of the HTTP service."`
  Namespace string `yaml:"-"`
 }
 

extensions/graph/pkg/config/config.go

@@ -29,7 +29,7 @@ type Config struct {
 }
 
 type Spaces struct {
- WebDavBase string `yaml:"webdav_base" env:"OCIS_URL;GRAPH_SPACES_WEBDAV_BASE"`
+ WebDavBase string `yaml:"webdav_base" env:"OCIS_URL;GRAPH_SPACES_WEBDAV_BASE" desc:"URL, where oCIS is reachable for users."`
  WebDavPath string `yaml:"webdav_path" env:"GRAPH_SPACES_WEBDAV_PATH"`
  DefaultQuota string `yaml:"default_quota" env:"GRAPH_SPACES_DEFAULT_QUOTA"`
  Insecure bool `yaml:"insecure" env:"OCIS_INSECURE;GRAPH_SPACES_INSECURE"`

extensions/graph/pkg/config/http.go

@@ -2,7 +2,7 @@ package config
 
 // HTTP defines the available http configuration.
 type HTTP struct {
- Addr string `yaml:"addr" env:"GRAPH_HTTP_ADDR"`
+ Addr string `yaml:"addr" env:"GRAPH_HTTP_ADDR" desc:"The bind address of the HTTP service."`
  Namespace string `yaml:"-"`
- Root string `yaml:"root" env:"GRAPH_HTTP_ROOT"`
+ Root string `yaml:"root" env:"GRAPH_HTTP_ROOT" desc:"The root path of the HTTP service."`
 }

extensions/groups/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"GROUPS_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's groupmember ships in the reva access token. To reduces token size, especially when users are members of a large number of groups."`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"GROUPS_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the loading of user's group memberships from the reva access token."`
 
  Driver string `yaml:"driver" desc:"The driver which should be used by the groups service (e.g. ldap)."`
  Drivers Drivers `yaml:"drivers"`
@@ -52,7 +52,7 @@ type Debug struct {
 }
 
 type GRPCConfig struct {
- Addr string `yaml:"addr" env:"GROUPS_GRPC_ADDR" desc:"The address of the grpc service."`
+ Addr string `yaml:"addr" env:"GROUPS_GRPC_ADDR" desc:"The bind address of the GRPC service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"GROUPS_GRPC_PROTOCOL" desc:"The transport protocol of the grpc service."`
 }

extensions/idp/pkg/config/config.go

@@ -53,7 +53,7 @@ type Ldap struct {
 
 // Asset defines the available asset configuration.
 type Asset struct {
- Path string `yaml:"asset" env:"IDP_ASSET_PATH" desc:"Defines the path for the IDP assets."`
+ Path string `yaml:"asset" env:"IDP_ASSET_PATH" desc:"Serve IDP assets from a path on the filesystem instead of the builtin assets."`
 }
 
 type Client struct {

extensions/idp/pkg/config/http.go

@@ -2,8 +2,8 @@ package config
 
 // HTTP defines the available http configuration.
 type HTTP struct {
- Addr string `yaml:"addr" env:"IDP_HTTP_ADDR"`
- Root string `yaml:"root" env:"IDP_HTTP_ROOT"`
+ Addr string `yaml:"addr" env:"IDP_HTTP_ADDR" desc:"The bind address of the HTTP service."`
+ Root string `yaml:"root" env:"IDP_HTTP_ROOT" desc:"The root path of the HTTP service."`
  Namespace string `yaml:"-"`
  TLSCert string `yaml:"tls_cert" env:"IDP_TRANSPORT_TLS_CERT"`
  TLSKey string `yaml:"tls_key" env:"IDP_TRANSPORT_TLS_KEY"`

extensions/ocdav/pkg/config/config.go

@@ -18,18 +18,18 @@ type Config struct {
  TokenManager *TokenManager `yaml:"token_manager"`
  Reva *Reva `yaml:"reva"`
 
- SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"OCDAV_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the encoding of the user's group memberships in the reva access token. This reduces token size, especially when users are members of a large number of groups."`
+ SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"OCDAV_SKIP_USER_GROUPS_IN_TOKEN" desc:"Disables the loading of user's group memberships from the reva access token."`
 
  WebdavNamespace string `yaml:"webdav_namespace" env:"OCDAV_WEBDAV_NAMESPACE" desc:"Jail requests to /dav/webdav into this CS3 namespace. Supports template layouting with CS3 User properties."`
  FilesNamespace string `yaml:"files_namespace" env:"OCDAV_FILES_NAMESPACE" desc:"Jail requests to /dav/files/{username} into this CS3 namespace. Supports template layouting with CS3 User properties."`
  SharesNamespace string `yaml:"shares_namespace" env:"OCDAV_SHARES_NAMESPACE" desc:"The human readable path for the share jail. Relative to a users personal space root. Upcased intentionally."`
  // PublicURL used to redirect /s/{token} URLs to
- PublicURL string `yaml:"public_url" env:"OCIS_URL;OCDAV_PUBLIC_URL"`
+ PublicURL string `yaml:"public_url" env:"OCIS_URL;OCDAV_PUBLIC_URL" desc:"URL, where oCIS is reachable for users."`
 
  // Insecure certificates allowed when making requests to the gateway
  Insecure bool `yaml:"insecure" env:"OCIS_INSECURE;OCDAV_INSECURE"`
  // Timeout in seconds when making requests to the gateway
- Timeout int64 `yaml:"gateway_request_timeout" env:"OCDAV_GATEWAY_REQUEST_TIMEOUT" desc:"Request timeout for ocdav gateway.`
+ Timeout int64 `yaml:"gateway_request_timeout" env:"OCDAV_GATEWAY_REQUEST_TIMEOUT" desc:"Request timeout for requests from the oCDAV service to the gateway service."`
  Middleware Middleware `yaml:"middleware"`
 
  Context context.Context `yaml:"-"`
@@ -61,7 +61,7 @@ type Debug struct {
 }
 
 type HTTPConfig struct {
- Addr string `yaml:"addr" env:"OCDAV_HTTP_ADDR" desc:"The address of the http service."`
+ Addr string `yaml:"addr" env:"OCDAV_HTTP_ADDR" desc:"The bind address of the HTTP service."`
  Namespace string `yaml:"-"`
  Protocol string `yaml:"protocol" env:"OCDAV_HTTP_PROTOCOL" desc:"The transport protocol of the http service."`
  Prefix string `yaml:"prefix" env:"OCDAV_HTTP_PREFIX" desc:"A URL path prefix for the handler."`

extensions/ocs/pkg/config/http.go

@@ -2,8 +2,8 @@ package config
 
 // HTTP defines the available http configuration.
 type HTTP struct {
- Addr string `yaml:"addr" env:"OCS_HTTP_ADDR"`
- Root string `yaml:"root" env:"OCS_HTTP_ROOT"`
+ Addr string `yaml:"addr" env:"OCS_HTTP_ADDR" desc:"The bind address of the HTTP service."`
+ Root string `yaml:"root" env:"OCS_HTTP_ROOT" desc:"The root path of the HTTP service."`
  Namespace string `yaml:"-"`
  CORS CORS `yaml:"cors"`
 }