Merge pull request #247384 from jtbx/nextcloud-doc

nixos/nextcloud: improve documentation

1 files changed, 52 insertions, 43 deletions

diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix
index 078164866dd62..503db124635cc 100644
--- a/nixos/modules/services/web-apps/nextcloud.nix
+++ b/nixos/modules/services/web-apps/nextcloud.nix
@@ -142,8 +142,8 @@ in {
       default = config.services.nextcloud.home;
       defaultText = literalExpression "config.services.nextcloud.home";
       description = lib.mdDoc ''
-        Data storage path of nextcloud.  Will be [](#opt-services.nextcloud.home) by default.
-        This folder will be populated with a config.php and data folder which contains the state of the instance (excl the database).";
+        Nextcloud's data storage path.  Will be [](#opt-services.nextcloud.home) by default.
+        This folder will be populated with a config.php file and a data folder which contains the state of the instance (excluding the database).";
       '';
       example = "/mnt/nextcloud-file";
     };
@@ -176,8 +176,8 @@ in {
       type = types.bool;
       default = true;
       description = lib.mdDoc ''
-        Automatically enable the apps in [](#opt-services.nextcloud.extraApps) every time nextcloud starts.
-        If set to false, apps need to be enabled in the Nextcloud user interface or with nextcloud-occ app:enable.
+        Automatically enable the apps in [](#opt-services.nextcloud.extraApps) every time Nextcloud starts.
+        If set to false, apps need to be enabled in the Nextcloud web user interface or with `nextcloud-occ app:enable`.
       '';
     };
     appstoreEnable = mkOption {
@@ -185,16 +185,28 @@ in {
       default = null;
       example = true;
       description = lib.mdDoc ''
-        Allow the installation of apps and app updates from the store.
+        Allow the installation and updating of apps from the Nextcloud appstore.
         Enabled by default unless there are packages in [](#opt-services.nextcloud.extraApps).
-        Set to true to force enable the store even if [](#opt-services.nextcloud.extraApps) is used.
-        Set to false to disable the installation of apps from the global appstore. App management is always enabled regardless of this setting.
+        Set this to true to force enable the store even if [](#opt-services.nextcloud.extraApps) is used.
+        Set this to false to disable the installation of apps from the global appstore. App management is always enabled regardless of this setting.
       '';
     };
     logLevel = mkOption {
       type = types.ints.between 0 4;
       default = 2;
-      description = lib.mdDoc "Log level value between 0 (DEBUG) and 4 (FATAL).";
+      description = lib.mdDoc ''
+        Log level value between 0 (DEBUG) and 4 (FATAL).
+
+        - 0 (debug): Log all activity.
+
+        - 1 (info): Log activity such as user logins and file activities, plus warnings, errors, and fatal errors.
+
+        - 2 (warn): Log successful operations, as well as warnings of potential problems, errors and fatal errors.
+
+        - 3 (error): Log failed operations and fatal errors.
+
+        - 4 (fatal): Log only fatal errors that cause the server to stop.
+      '';
     };
     logType = mkOption {
       type = types.enum [ "errorlog" "file" "syslog" "systemd" ];
@@ -208,7 +220,7 @@ in {
     https = mkOption {
       type = types.bool;
       default = false;
-      description = lib.mdDoc "Use https for generated links.";
+      description = lib.mdDoc "Use HTTPS for generated links.";
     };
     package = mkOption {
       type = types.package;
@@ -228,7 +240,7 @@ in {
       default = "512M";
       type = types.str;
       description = lib.mdDoc ''
-        Defines the upload limit for files. This changes the relevant options
+        The upload limit for files. This changes the relevant options
         in php.ini and nginx if enabled.
       '';
     };
@@ -257,10 +269,10 @@ in {
       default = all: [];
       defaultText = literalExpression "all: []";
       description = lib.mdDoc ''
-        Additional PHP extensions to use for nextcloud.
-        By default, only extensions necessary for a vanilla nextcloud installation are enabled,
+        Additional PHP extensions to use for Nextcloud.
+        By default, only extensions necessary for a vanilla Nextcloud installation are enabled,
         but you may choose from the list of available extensions and add further ones.
-        This is sometimes necessary to be able to install a certain nextcloud app that has additional requirements.
+        This is sometimes necessary to be able to install a certain Nextcloud app that has additional requirements.
       '';
       example = literalExpression ''
         all: [ all.pdlib all.bz2 ]
@@ -318,7 +330,7 @@ in {
       type = types.nullOr types.lines;
       default = null;
       description = lib.mdDoc ''
-        Options for nextcloud's PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives.
+        Options for Nextcloud's PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives.
       '';
     };
 
@@ -336,7 +348,7 @@ in {
         type = types.bool;
         default = false;
         description = lib.mdDoc ''
-          Create the database and database user locally.
+          Whether to create the database and database user locally.
         '';
       };
 
@@ -374,9 +386,10 @@ in {
           else "localhost";
         defaultText = "localhost";
         description = lib.mdDoc ''
-          Database host or socket path. Defaults to the correct unix socket
-          instead if `services.nextcloud.database.createLocally` is true and
-          `services.nextcloud.config.dbtype` is either `pgsql` or `mysql`.
+          Database host or socket path.
+          If [](#opt-services.nextcloud.database.createLocally) is true and
+          [](#opt-services.nextcloud.config.dbtype) is either `pgsql` or `mysql`,
+          defaults to the correct Unix socket instead.
         '';
       };
       dbport = mkOption {
@@ -387,19 +400,19 @@ in {
       dbtableprefix = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = lib.mdDoc "Table prefix in Nextcloud database.";
+        description = lib.mdDoc "Table prefix in Nextcloud's database.";
       };
       adminuser = mkOption {
         type = types.str;
         default = "root";
-        description = lib.mdDoc "Admin username.";
+        description = lib.mdDoc "Username for the admin account.";
       };
       adminpassFile = mkOption {
         type = types.str;
         description = lib.mdDoc ''
           The full path to a file that contains the admin's password. Must be
           readable by user `nextcloud`. The password is set only in the initial
-          setup of nextcloud by the systemd `nextcloud-setup.service`.
+          setup of Nextcloud by the systemd service `nextcloud-setup.service`.
         '';
       };
 
@@ -407,7 +420,7 @@ in {
         type = types.listOf types.str;
         default = [];
         description = lib.mdDoc ''
-          Trusted domains, from which the nextcloud installation will be
+          Trusted domains from which the Nextcloud installation will be
           accessible.  You don't need to add
           `services.nextcloud.hostname` here.
         '';
@@ -417,8 +430,8 @@ in {
         type = types.listOf types.str;
         default = [];
         description = lib.mdDoc ''
-          Trusted proxies, to provide if the nextcloud installation is being
-          proxied to secure against e.g. spoofing.
+          Trusted proxies to provide if the Nextcloud installation is being
+          proxied to secure against, e.g. spoofing.
         '';
       };
 
@@ -428,10 +441,10 @@ in {
         example = "https";
 
         description = lib.mdDoc ''
-          Force Nextcloud to always use HTTPS i.e. for link generation. Nextcloud
-          uses the currently used protocol by default, but when behind a reverse-proxy,
-          it may use `http` for everything although Nextcloud
-          may be served via HTTPS.
+          Force Nextcloud to always use HTTP or HTTPS i.e. for link generation.
+          Nextcloud uses the currently used protocol by default, but when
+          behind a reverse-proxy, it may use `http` for everything although
+          Nextcloud may be served via HTTPS.
         '';
       };
 
@@ -440,16 +453,12 @@ in {
         type = types.nullOr types.str;
         example = "DE";
         description = lib.mdDoc ''
-          ::: {.warning}
-          This option exists since Nextcloud 21! If older versions are used,
-          this will throw an eval-error!
-          :::
-
-          [ISO 3611-1](https://www.iso.org/iso-3166-country-codes.html)
-          country codes for automatic phone-number detection without a country code.
+          An [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html)
+          country code which replaces automatic phone-number detection
+          without a country code.
 
-          With e.g. `DE` set, the `+49` can be omitted for
-          phone-numbers.
+          As an example, with `DE` set as the default phone region,
+          the `+49` prefix can be omitted for phone numbers.
         '';
       };
 
@@ -574,10 +583,10 @@ in {
       default = config.services.nextcloud.notify_push.enable;
       defaultText = literalExpression "config.services.nextcloud.notify_push.enable";
       description = lib.mdDoc ''
-        Whether to configure nextcloud to use the recommended redis settings for small instances.
+        Whether to configure Nextcloud to use the recommended Redis settings for small instances.
 
         ::: {.note}
-        The `notify_push` app requires redis to be configured. If this option is turned off, this must be configured manually.
+        The `notify_push` app requires Redis to be configured. If this option is turned off, this must be configured manually.
         :::
       '';
     };
@@ -614,7 +623,7 @@ in {
         type = types.bool;
         default = false;
         description = lib.mdDoc ''
-          Run regular auto update of all apps installed from the nextcloud app store.
+          Run a regular auto-update of all apps installed from the Nextcloud app store.
         '';
       };
       startAt = mkOption {
@@ -661,7 +670,7 @@ in {
       type = jsonFormat.type;
       default = {};
       description = lib.mdDoc ''
-        Extra options which should be appended to nextcloud's config.php file.
+        Extra options which should be appended to Nextcloud's config.php file.
       '';
       example = literalExpression '' {
         redis = {
@@ -678,7 +687,7 @@ in {
       type = types.nullOr types.str;
       default = null;
       description = lib.mdDoc ''
-        Secret options which will be appended to nextcloud's config.php file (written as JSON, in the same
+        Secret options which will be appended to Nextcloud's config.php file (written as JSON, in the same
         form as the [](#opt-services.nextcloud.extraOptions) option), for example
         `{"redis":{"password":"secret"}}`.
       '';
@@ -712,7 +721,7 @@ in {
             A legacy Nextcloud install (from before NixOS ${nixos}) may be installed.
 
             After nextcloud${toString major} is installed successfully, you can safely upgrade
-            to ${toString (major + 1)}. The latest version available is nextcloud${toString latest}.
+            to ${toString (major + 1)}. The latest version available is Nextcloud${toString latest}.
 
             Please note that Nextcloud doesn't support upgrades across multiple major versions
             (i.e. an upgrade from 16 is possible to 17, but not 16 to 18).