From 2d564521c094b17e88707ac95cb4b6331b1b709a Mon Sep 17 00:00:00 2001 From: pennae Date: Sun, 5 Dec 2021 22:06:49 +0100 Subject: [PATCH] treewide: add literalDocBook text to options with complex defaults some options have default that are best described in prose, such as defaults that depend on the system stateVersion, defaults that are derivations specific to the surrounding context, or those where the expression is much longer and harder to understand than a simple text snippet. --- nixos/modules/programs/gnupg.nix | 1 + nixos/modules/services/audio/mpdscribble.nix | 4 ++++ .../cluster/kubernetes/addons/dns.nix | 6 ++++- .../services/cluster/kubernetes/kubelet.nix | 1 + .../services/computing/slurm/slurm.nix | 4 ++++ .../modules/services/games/quake3-server.nix | 1 + nixos/modules/services/misc/gitweb.nix | 1 + .../modules/services/misc/matrix-synapse.nix | 23 ++++++++++++++++++ nixos/modules/services/misc/rippled.nix | 1 + nixos/modules/services/monitoring/thanos.nix | 3 +++ .../modules/services/networking/firewall.nix | 1 + .../modules/services/networking/syncthing.nix | 24 +++++++++++++++++-- nixos/modules/services/web-apps/keycloak.nix | 1 + nixos/modules/services/web-apps/nextcloud.nix | 1 + .../web-servers/lighttpd/collectd.nix | 6 ++++- .../services/x11/display-managers/default.nix | 3 +++ .../system/activation/activation-script.nix | 1 + nixos/modules/system/boot/plymouth.nix | 8 ++++++- nixos/modules/tasks/filesystems/zfs.nix | 1 + nixos/modules/virtualisation/cri-o.nix | 4 ++++ 20 files changed, 90 insertions(+), 5 deletions(-) diff --git a/nixos/modules/programs/gnupg.nix b/nixos/modules/programs/gnupg.nix index 06f49182e4df..fe5d7bd834b2 100644 --- a/nixos/modules/programs/gnupg.nix +++ b/nixos/modules/programs/gnupg.nix @@ -71,6 +71,7 @@ in type = types.nullOr (types.enum pkgs.pinentry.flavors); example = "gnome3"; default = defaultPinentryFlavor; + defaultText = literalDocBook ''matching the configured desktop environment''; description = '' Which pinentry interface to use. If not null, the path to the pinentry binary will be passed to gpg-agent via commandline and diff --git a/nixos/modules/services/audio/mpdscribble.nix b/nixos/modules/services/audio/mpdscribble.nix index 57d3ef77b34e..333ffb709410 100644 --- a/nixos/modules/services/audio/mpdscribble.nix +++ b/nixos/modules/services/audio/mpdscribble.nix @@ -128,6 +128,10 @@ in { mpdCfg.credentials).passwordFile else null; + defaultText = literalDocBook '' + The first password file with read access configured for MPD when using a local instance, + otherwise null. + ''; type = types.nullOr types.str; description = '' File containing the password for the mpd daemon. diff --git a/nixos/modules/services/cluster/kubernetes/addons/dns.nix b/nixos/modules/services/cluster/kubernetes/addons/dns.nix index 34943fddd3d1..10f45db7883f 100644 --- a/nixos/modules/services/cluster/kubernetes/addons/dns.nix +++ b/nixos/modules/services/cluster/kubernetes/addons/dns.nix @@ -1,4 +1,4 @@ -{ config, pkgs, lib, ... }: +{ config, options, pkgs, lib, ... }: with lib; @@ -23,6 +23,10 @@ in { take 3 (splitString "." config.services.kubernetes.apiserver.serviceClusterIpRange )) ) + ".254"; + defaultText = literalDocBook '' + The x.y.z.254 IP of + config.${options.services.kubernetes.apiserver.serviceClusterIpRange}. + ''; type = types.str; }; diff --git a/nixos/modules/services/cluster/kubernetes/kubelet.nix b/nixos/modules/services/cluster/kubernetes/kubelet.nix index 4c00e162efa8..3a15984c2305 100644 --- a/nixos/modules/services/cluster/kubernetes/kubelet.nix +++ b/nixos/modules/services/cluster/kubernetes/kubelet.nix @@ -36,6 +36,7 @@ let key = mkOption { description = "Key of taint."; default = name; + defaultText = literalDocBook "Name of this submodule."; type = str; }; value = mkOption { diff --git a/nixos/modules/services/computing/slurm/slurm.nix b/nixos/modules/services/computing/slurm/slurm.nix index 02dfe2fe882f..aa0be8726f0e 100644 --- a/nixos/modules/services/computing/slurm/slurm.nix +++ b/nixos/modules/services/computing/slurm/slurm.nix @@ -281,6 +281,10 @@ in type = types.path; internal = true; default = etcSlurm; + defaultText = literalDocBook '' + Directory created from generated config files and + config.${opt.extraConfigPaths}. + ''; description = '' Path to directory with slurm config files. This option is set by default from the Slurm module and is meant to make the Slurm config file available to other modules. diff --git a/nixos/modules/services/games/quake3-server.nix b/nixos/modules/services/games/quake3-server.nix index 1dc01260e8fa..175af4a83828 100644 --- a/nixos/modules/services/games/quake3-server.nix +++ b/nixos/modules/services/games/quake3-server.nix @@ -71,6 +71,7 @@ in { baseq3 = mkOption { type = types.either types.package types.path; default = defaultBaseq3; + defaultText = literalDocBook "Manually downloaded Quake 3 installation directory."; example = "/var/lib/q3ds"; description = '' Path to the baseq3 files (pak*.pk3). If this is on the nix store (type = package) all .pk3 files should be saved diff --git a/nixos/modules/services/misc/gitweb.nix b/nixos/modules/services/misc/gitweb.nix index 13396bf2eb02..a1180716e36b 100644 --- a/nixos/modules/services/misc/gitweb.nix +++ b/nixos/modules/services/misc/gitweb.nix @@ -47,6 +47,7 @@ in $highlight_bin = "${pkgs.highlight}/bin/highlight"; ${cfg.extraConfig} ''; + defaultText = literalDocBook "generated config file"; type = types.path; readOnly = true; internal = true; diff --git a/nixos/modules/services/misc/matrix-synapse.nix b/nixos/modules/services/misc/matrix-synapse.nix index 90e2dbfafa15..df9217cc5277 100644 --- a/nixos/modules/services/misc/matrix-synapse.nix +++ b/nixos/modules/services/misc/matrix-synapse.nix @@ -403,6 +403,29 @@ in { database = cfg.database_name; }; }.${cfg.database_type}; + defaultText = literalDocBook '' + + + using sqlite3 + + + { database = "''${config.${opt.dataDir}}/homeserver.db"; } + + + + + using psycopg2 + + + psycopg2 = { + user = config.${opt.database_user}; + database = config.${opt.database_name}; + } + + + + + ''; description = '' Arguments to pass to the engine. ''; diff --git a/nixos/modules/services/misc/rippled.nix b/nixos/modules/services/misc/rippled.nix index 67768a97bfb6..f6ec0677774b 100644 --- a/nixos/modules/services/misc/rippled.nix +++ b/nixos/modules/services/misc/rippled.nix @@ -401,6 +401,7 @@ in config = mkOption { internal = true; default = pkgs.writeText "rippled.conf" rippledCfg; + defaultText = literalDocBook "generated config file"; }; }; }; diff --git a/nixos/modules/services/monitoring/thanos.nix b/nixos/modules/services/monitoring/thanos.nix index da626788d827..9e93d8dbb0ef 100644 --- a/nixos/modules/services/monitoring/thanos.nix +++ b/nixos/modules/services/monitoring/thanos.nix @@ -83,6 +83,9 @@ let mkArgumentsOption = cmd: mkOption { type = types.listOf types.str; default = argumentsOf cmd; + defaultText = literalDocBook '' + calculated from config.services.thanos.${cmd} + ''; description = '' Arguments to the thanos ${cmd} command. diff --git a/nixos/modules/services/networking/firewall.nix b/nixos/modules/services/networking/firewall.nix index b5b46fe6042c..ff023a888f26 100644 --- a/nixos/modules/services/networking/firewall.nix +++ b/nixos/modules/services/networking/firewall.nix @@ -421,6 +421,7 @@ in checkReversePath = mkOption { type = types.either types.bool (types.enum ["strict" "loose"]); default = kernelHasRPFilter; + defaultText = literalDocBook "true if supported by the chosen kernel"; example = "loose"; description = '' diff --git a/nixos/modules/services/networking/syncthing.nix b/nixos/modules/services/networking/syncthing.nix index 8c44687a3822..e37e324019e8 100644 --- a/nixos/modules/services/networking/syncthing.nix +++ b/nixos/modules/services/networking/syncthing.nix @@ -1,9 +1,10 @@ -{ config, lib, pkgs, ... }: +{ config, lib, options, pkgs, ... }: with lib; let cfg = config.services.syncthing; + opt = options.services.syncthing; defaultUser = "syncthing"; defaultGroup = defaultUser; @@ -431,7 +432,26 @@ in { The path where the settings and keys will exist. ''; default = cfg.dataDir + optionalString cond "/.config/syncthing"; - defaultText = literalExpression "dataDir${optionalString cond " + \"/.config/syncthing\""}"; + defaultText = literalDocBook '' + + + stateVersion >= 19.03 + + + config.${opt.dataDir} + "/.config/syncthing" + + + + + otherwise + + + config.${opt.dataDir} + + + + + ''; }; extraFlags = mkOption { diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index fac8e08b3597..e08f6dcabd2f 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -140,6 +140,7 @@ in lib.mkOption { type = lib.types.port; default = dbPorts.${cfg.database.type}; + defaultText = lib.literalDocBook "default port of selected database"; description = '' Port of the database to connect to. ''; diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix index 04ec7888950d..dfc80bbbf428 100644 --- a/nixos/modules/services/web-apps/nextcloud.nix +++ b/nixos/modules/services/web-apps/nextcloud.nix @@ -499,6 +499,7 @@ in { occ = mkOption { type = types.package; default = occ; + defaultText = literalDocBook "generated script"; internal = true; description = '' The nextcloud-occ program preconfigured to target this Nextcloud instance. diff --git a/nixos/modules/services/web-servers/lighttpd/collectd.nix b/nixos/modules/services/web-servers/lighttpd/collectd.nix index 3f262451c2cb..5f091591daf9 100644 --- a/nixos/modules/services/web-servers/lighttpd/collectd.nix +++ b/nixos/modules/services/web-servers/lighttpd/collectd.nix @@ -1,9 +1,10 @@ -{ config, lib, pkgs, ... }: +{ config, lib, options, pkgs, ... }: with lib; let cfg = config.services.lighttpd.collectd; + opt = options.services.lighttpd.collectd; collectionConf = pkgs.writeText "collection.conf" '' datadir: "${config.services.collectd.dataDir}" @@ -29,6 +30,9 @@ in collectionCgi = mkOption { type = types.path; default = defaultCollectionCgi; + defaultText = literalDocBook '' + config.${options.services.collectd.package} configured for lighttpd + ''; description = '' Path to collection.cgi script from (collectd sources)/contrib/collection.cgi This option allows to use a customized version diff --git a/nixos/modules/services/x11/display-managers/default.nix b/nixos/modules/services/x11/display-managers/default.nix index 3adb50c678e4..58e4fe04f373 100644 --- a/nixos/modules/services/x11/display-managers/default.nix +++ b/nixos/modules/services/x11/display-managers/default.nix @@ -279,6 +279,9 @@ in defaultSessionFromLegacyOptions else null; + defaultText = literalDocBook '' + Taken from display manager settings or window manager settings, if either is set. + ''; example = "gnome"; description = '' Graphical session to pre-select in the session chooser (only effective for GDM, LightDM and SDDM). diff --git a/nixos/modules/system/activation/activation-script.nix b/nixos/modules/system/activation/activation-script.nix index 8dbfe393f109..154b6127b27f 100644 --- a/nixos/modules/system/activation/activation-script.nix +++ b/nixos/modules/system/activation/activation-script.nix @@ -142,6 +142,7 @@ in readOnly = true; internal = true; default = systemActivationScript (removeAttrs config.system.activationScripts [ "script" ]) true; + defaultText = literalDocBook "generated activation script"; }; system.userActivationScripts = mkOption { diff --git a/nixos/modules/system/boot/plymouth.nix b/nixos/modules/system/boot/plymouth.nix index 4b8194d2f85c..78ae8e9d20b7 100644 --- a/nixos/modules/system/boot/plymouth.nix +++ b/nixos/modules/system/boot/plymouth.nix @@ -1,4 +1,4 @@ -{ config, lib, pkgs, ... }: +{ config, lib, options, pkgs, ... }: with lib; @@ -7,6 +7,7 @@ let inherit (pkgs) plymouth nixos-icons; cfg = config.boot.plymouth; + opt = options.boot.plymouth; nixosBreezePlymouth = pkgs.plasma5Packages.breeze-plymouth.override { logoFile = cfg.logo; @@ -71,6 +72,11 @@ in themePackages = mkOption { default = lib.optional (cfg.theme == "breeze") nixosBreezePlymouth; + defaultText = literalDocBook '' + A NixOS branded variant of the breeze theme when + config.${opt.theme} == "breeze", otherwise + [ ]. + ''; type = types.listOf types.package; description = '' Extra theme packages for plymouth. diff --git a/nixos/modules/tasks/filesystems/zfs.nix b/nixos/modules/tasks/filesystems/zfs.nix index 65364801c32a..a9100da1aa40 100644 --- a/nixos/modules/tasks/filesystems/zfs.nix +++ b/nixos/modules/tasks/filesystems/zfs.nix @@ -112,6 +112,7 @@ in readOnly = true; type = types.bool; default = inInitrd || inSystem; + defaultText = literalDocBook "true if ZFS filesystem support is enabled"; description = "True if ZFS filesystem support is enabled"; }; diff --git a/nixos/modules/virtualisation/cri-o.nix b/nixos/modules/virtualisation/cri-o.nix index 38766113f391..cf5110001503 100644 --- a/nixos/modules/virtualisation/cri-o.nix +++ b/nixos/modules/virtualisation/cri-o.nix @@ -71,6 +71,10 @@ in package = mkOption { type = types.package; default = crioPackage; + defaultText = literalDocBook '' + pkgs.cri-o built with + config.${opt.extraPackages}. + ''; internal = true; description = '' The final CRI-O package (including extra packages).