From 1013069f52123135cc1d96b2b7d77606a22d3b33 Mon Sep 17 00:00:00 2001 From: pennae Date: Mon, 29 Aug 2022 21:48:56 +0200 Subject: [PATCH] nixos/*: convert more partially-md option descriptions this mostly means marking options that use markdown already appropriately and making a few adjustments so they still render correctly. notable for nftables we have to transform the md links because the manpage would not render them correctly otherwise. --- nixos/modules/installer/sd-card/sd-image.nix | 2 +- nixos/modules/programs/feedbackd.nix | 4 ++-- nixos/modules/services/backup/restic.nix | 6 +++--- nixos/modules/services/logging/logrotate.nix | 6 +++--- nixos/modules/services/mail/dkimproxy-out.nix | 2 +- nixos/modules/services/mail/sympa.nix | 4 ++-- nixos/modules/services/misc/klipper.nix | 4 ++-- nixos/modules/services/misc/mbpfan.nix | 6 +++--- nixos/modules/services/misc/zoneminder.nix | 4 ++-- nixos/modules/services/monitoring/ups.nix | 2 +- nixos/modules/services/networking/bitlbee.nix | 6 +++--- nixos/modules/services/networking/lokinet.nix | 4 ++-- nixos/modules/services/networking/nftables.nix | 11 +++++------ nixos/modules/services/networking/quassel.nix | 6 +++--- nixos/modules/services/networking/seafile.nix | 4 ++-- nixos/modules/services/networking/soju.nix | 2 +- nixos/modules/services/networking/x2goserver.nix | 2 +- nixos/modules/services/system/earlyoom.nix | 8 ++++---- nixos/modules/services/system/systembus-notify.nix | 4 ++-- nixos/modules/services/torrent/transmission.nix | 4 ++-- nixos/modules/virtualisation/qemu-vm.nix | 11 +++++------ 21 files changed, 50 insertions(+), 52 deletions(-) diff --git a/nixos/modules/installer/sd-card/sd-image.nix b/nixos/modules/installer/sd-card/sd-image.nix index e192312649e2..cb2522d86789 100644 --- a/nixos/modules/installer/sd-card/sd-image.nix +++ b/nixos/modules/installer/sd-card/sd-image.nix @@ -58,7 +58,7 @@ in firmwarePartitionOffset = mkOption { type = types.int; default = 8; - description = '' + description = lib.mdDoc '' Gap in front of the /boot/firmware partition, in mebibytes (1024×1024 bytes). Can be increased to make more space for boards requiring to dd u-boot diff --git a/nixos/modules/programs/feedbackd.nix b/nixos/modules/programs/feedbackd.nix index 7e6cf829467d..cee8daa31462 100644 --- a/nixos/modules/programs/feedbackd.nix +++ b/nixos/modules/programs/feedbackd.nix @@ -7,11 +7,11 @@ let in { options = { programs.feedbackd = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Whether to enable the feedbackd D-BUS service and udev rules. Your user needs to be in the `feedbackd` group to trigger effects. - ''; + ''); package = mkOption { description = lib.mdDoc '' Which feedbackd package to use. diff --git a/nixos/modules/services/backup/restic.nix b/nixos/modules/services/backup/restic.nix index 2b0dcb16344c..65fe34b2d39e 100644 --- a/nixos/modules/services/backup/restic.nix +++ b/nixos/modules/services/backup/restic.nix @@ -182,11 +182,11 @@ in pruneOpts = mkOption { type = types.listOf types.str; default = [ ]; - description = '' - A list of options (--keep-* et al.) for 'restic forget + description = lib.mdDoc '' + A list of options (--keep-\* et al.) for 'restic forget --prune', to automatically prune old snapshots. The 'forget' command is run *after* the 'backup' command, so - keep that in mind when constructing the --keep-* options. + keep that in mind when constructing the --keep-\* options. ''; example = [ "--keep-daily 7" diff --git a/nixos/modules/services/logging/logrotate.nix b/nixos/modules/services/logging/logrotate.nix index 3ea130a891d4..6f20b6cd7458 100644 --- a/nixos/modules/services/logging/logrotate.nix +++ b/nixos/modules/services/logging/logrotate.nix @@ -316,11 +316,11 @@ in paths = mkOption { type = with types; attrsOf (submodule pathOpts); default = { }; - description = '' + description = lib.mdDoc '' Attribute set of paths to rotate. The order each block appears in the generated configuration file - can be controlled by the priority option + can be controlled by the [priority](#opt-services.logrotate.paths._name_.priority) option using the same semantics as `lib.mkOrder`. Smaller values have a greater priority. - This setting has been deprecated in favor of logrotate settings. + This setting has been deprecated in favor of [logrotate settings](#opt-services.logrotate.settings). ''; example = literalExpression '' { diff --git a/nixos/modules/services/mail/dkimproxy-out.nix b/nixos/modules/services/mail/dkimproxy-out.nix index aa465891db21..6f9cbc4e9d4d 100644 --- a/nixos/modules/services/mail/dkimproxy-out.nix +++ b/nixos/modules/services/mail/dkimproxy-out.nix @@ -45,7 +45,7 @@ in type = types.str; example = "selector1"; description = - '' + lib.mdDoc '' The selector to use for DKIM key identification. For example, if 'selector1' is used here, then for each domain diff --git a/nixos/modules/services/mail/sympa.nix b/nixos/modules/services/mail/sympa.nix index 0014701d5831..f33d0886eace 100644 --- a/nixos/modules/services/mail/sympa.nix +++ b/nixos/modules/services/mail/sympa.nix @@ -239,10 +239,10 @@ in server = mkOption { type = enum [ "nginx" "none" ]; default = "nginx"; - description = '' + description = lib.mdDoc '' The webserver used for the Sympa web interface. Set it to `none` if you want to configure it yourself. Further nginx configuration can be done by adapting - . + {option}`services.nginx.virtualHosts.«name»`. ''; }; diff --git a/nixos/modules/services/misc/klipper.nix b/nixos/modules/services/misc/klipper.nix index 0dadc0c74705..5fff1db3c6ae 100644 --- a/nixos/modules/services/misc/klipper.nix +++ b/nixos/modules/services/misc/klipper.nix @@ -76,10 +76,10 @@ in type = with types; attrsOf (submodule { options = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' building of firmware and addition of klipper-flash tools for manual flashing. This will add `klipper-flash-$mcu` scripts to your environment which can be called to flash the firmware. - ''; + ''); configFile = mkOption { type = path; description = lib.mdDoc "Path to firmware config which is generated using `klipper-genconf`"; diff --git a/nixos/modules/services/misc/mbpfan.nix b/nixos/modules/services/misc/mbpfan.nix index 786ecf2d696f..e99fa365f7ab 100644 --- a/nixos/modules/services/misc/mbpfan.nix +++ b/nixos/modules/services/misc/mbpfan.nix @@ -38,10 +38,10 @@ in { options.general.min_fan1_speed = mkOption { type = types.nullOr types.int; default = 2000; - description = '' + description = lib.mdDoc '' You can check minimum and maximum fan limits with - "cat /sys/devices/platform/applesmc.768/fan*_min" and - "cat /sys/devices/platform/applesmc.768/fan*_max" respectively. + `cat /sys/devices/platform/applesmc.768/fan*_min` and + `cat /sys/devices/platform/applesmc.768/fan*_max` respectively. Setting to null implies using default value from applesmc. ''; }; diff --git a/nixos/modules/services/misc/zoneminder.nix b/nixos/modules/services/misc/zoneminder.nix index fa0e06a01480..e031fab5970b 100644 --- a/nixos/modules/services/misc/zoneminder.nix +++ b/nixos/modules/services/misc/zoneminder.nix @@ -66,7 +66,7 @@ let in { options = { services.zoneminder = with lib; { - enable = lib.mkEnableOption '' + enable = lib.mkEnableOption (lib.mdDoc '' ZoneMinder If you intend to run the database locally, you should set @@ -75,7 +75,7 @@ in { and database user as well as populate the database yourself. Additionally, you will need to run `zmupdate.pl` yourself when upgrading to a newer version. - ''; + ''); webserver = mkOption { type = types.enum [ "nginx" "none" ]; diff --git a/nixos/modules/services/monitoring/ups.nix b/nixos/modules/services/monitoring/ups.nix index 8af2c2a1f253..c7abaeb2973e 100644 --- a/nixos/modules/services/monitoring/ups.nix +++ b/nixos/modules/services/monitoring/ups.nix @@ -116,7 +116,7 @@ in mode = mkOption { default = "standalone"; type = types.str; - description = '' + description = lib.mdDoc '' The MODE determines which part of the NUT is to be started, and which configuration files must be modified. diff --git a/nixos/modules/services/networking/bitlbee.nix b/nixos/modules/services/networking/bitlbee.nix index e2844feda028..668ed388ae2c 100644 --- a/nixos/modules/services/networking/bitlbee.nix +++ b/nixos/modules/services/networking/bitlbee.nix @@ -59,9 +59,9 @@ in interface = mkOption { type = types.str; default = "127.0.0.1"; - description = '' - The interface the BitlBee deamon will be listening to. If `127.0.0.1', - only clients on the local host can connect to it; if `0.0.0.0', clients + description = lib.mdDoc '' + The interface the BitlBee deamon will be listening to. If `127.0.0.1`, + only clients on the local host can connect to it; if `0.0.0.0`, clients can access it from any network interface. ''; }; diff --git a/nixos/modules/services/networking/lokinet.nix b/nixos/modules/services/networking/lokinet.nix index 59622d173a35..0347c3b43290 100644 --- a/nixos/modules/services/networking/lokinet.nix +++ b/nixos/modules/services/networking/lokinet.nix @@ -65,9 +65,9 @@ in with lib; { exit-node = [ "example.loki" ]; # maps all exit traffic to example.loki exit-node = [ "example.loki:100.0.0.0/24" ]; # maps 100.0.0.0/24 to example.loki ''; - description = '' + description = lib.mdDoc '' Specify a `.loki` address and an optional ip range to use as an exit broker. - See for + See for a list of exit nodes. ''; }; diff --git a/nixos/modules/services/networking/nftables.nix b/nixos/modules/services/networking/nftables.nix index 008528ad35bb..d2d7543e8cf3 100644 --- a/nixos/modules/services/networking/nftables.nix +++ b/nixos/modules/services/networking/nftables.nix @@ -11,7 +11,7 @@ in type = types.bool; default = false; description = - '' + lib.mdDoc '' Whether to enable nftables. nftables is a Linux-based packet filtering framework intended to replace frameworks like iptables. @@ -21,14 +21,13 @@ in Note that if you have Docker enabled you will not be able to use nftables without intervention. Docker uses iptables internally to setup NAT for containers. This module disables the ip_tables kernel - module, however Docker automatically loads the module. Please see [1] + module, however Docker automatically loads the module. Please see + for more information. There are other programs that use iptables internally too, such as - libvirt. For information on how the two firewalls interact, see [2]. - - [1]: https://github.com/NixOS/nixpkgs/issues/24318#issuecomment-289216273 - [2]: https://wiki.nftables.org/wiki-nftables/index.php/Troubleshooting#Question_4._How_do_nftables_and_iptables_interact_when_used_on_the_same_system.3F + libvirt. For information on how the two firewalls interact, see + . ''; }; networking.nftables.ruleset = mkOption { diff --git a/nixos/modules/services/networking/quassel.nix b/nixos/modules/services/networking/quassel.nix index a4b203ea0018..a0c34c2fa34a 100644 --- a/nixos/modules/services/networking/quassel.nix +++ b/nixos/modules/services/networking/quassel.nix @@ -47,9 +47,9 @@ in interfaces = mkOption { type = types.listOf types.str; default = [ "127.0.0.1" ]; - description = '' - The interfaces the Quassel daemon will be listening to. If `[ 127.0.0.1 ]', - only clients on the local host can connect to it; if `[ 0.0.0.0 ]', clients + description = lib.mdDoc '' + The interfaces the Quassel daemon will be listening to. If `[ 127.0.0.1 ]`, + only clients on the local host can connect to it; if `[ 0.0.0.0 ]`, clients can access it from any network interface. ''; }; diff --git a/nixos/modules/services/networking/seafile.nix b/nixos/modules/services/networking/seafile.nix index d9617952ea59..4a41f30b87b7 100644 --- a/nixos/modules/services/networking/seafile.nix +++ b/nixos/modules/services/networking/seafile.nix @@ -131,9 +131,9 @@ in { seahubExtraConf = mkOption { default = ""; type = types.lines; - description = '' + description = lib.mdDoc '' Extra config to append to `seahub_settings.py` file. - Refer to + Refer to for all available options. ''; }; diff --git a/nixos/modules/services/networking/soju.nix b/nixos/modules/services/networking/soju.nix index dddacea20044..df5032f536ac 100644 --- a/nixos/modules/services/networking/soju.nix +++ b/nixos/modules/services/networking/soju.nix @@ -79,7 +79,7 @@ in acceptProxyIP = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Allow the specified IPs to act as a proxy. Proxys have the ability to overwrite the remote and local connection addresses (via the X-Forwarded-\* HTTP header fields). The special name "localhost" accepts the loopback diff --git a/nixos/modules/services/networking/x2goserver.nix b/nixos/modules/services/networking/x2goserver.nix index a1e096c19a2a..e534a2a3dcac 100644 --- a/nixos/modules/services/networking/x2goserver.nix +++ b/nixos/modules/services/networking/x2goserver.nix @@ -22,7 +22,7 @@ in { ]; options.services.x2goserver = { - enable = mkEnableOption "x2goserver" // { + enable = mkEnableOption (lib.mdDoc "x2goserver") // { description = '' Enables the x2goserver module. NOTE: This will create a good amount of symlinks in `/usr/local/bin` diff --git a/nixos/modules/services/system/earlyoom.nix b/nixos/modules/services/system/earlyoom.nix index b2e2d21002ce..7d9c58e54034 100644 --- a/nixos/modules/services/system/earlyoom.nix +++ b/nixos/modules/services/system/earlyoom.nix @@ -72,7 +72,7 @@ in enableNotifications = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Send notifications about killed processes via the system d-bus. WARNING: enabling this option (while convenient) should *not* be done on a @@ -80,10 +80,10 @@ in local user to DoS your session by spamming notifications. To actually see the notifications in your GUI session, you need to have - systembus-notify running as your user, which this - option handles by enabling . + `systembus-notify` running as your user, which this + option handles by enabling {option}`services.systembus-notify`. - See README for details. + See [README](https://github.com/rfjakob/earlyoom#notifications) for details. ''; }; diff --git a/nixos/modules/services/system/systembus-notify.nix b/nixos/modules/services/system/systembus-notify.nix index e918bc552ece..269197b3997e 100644 --- a/nixos/modules/services/system/systembus-notify.nix +++ b/nixos/modules/services/system/systembus-notify.nix @@ -8,13 +8,13 @@ let in { options.services.systembus-notify = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' System bus notification support WARNING: enabling this option (while convenient) should *not* be done on a machine where you do not trust the other users as it allows any other local user to DoS your session by spamming notifications. - ''; + ''); }; config = mkIf cfg.enable { diff --git a/nixos/modules/services/torrent/transmission.nix b/nixos/modules/services/torrent/transmission.nix index 08abd86b4ec3..af0688f38879 100644 --- a/nixos/modules/services/torrent/transmission.nix +++ b/nixos/modules/services/torrent/transmission.nix @@ -108,9 +108,9 @@ in type = types.str; default = "127.0.0.1"; example = "0.0.0.0"; - description = '' + description = lib.mdDoc '' Where to listen for RPC connections. - Use \"0.0.0.0\" to listen on all interfaces. + Use `0.0.0.0` to listen on all interfaces. ''; }; options.rpc-port = mkOption { diff --git a/nixos/modules/virtualisation/qemu-vm.nix b/nixos/modules/virtualisation/qemu-vm.nix index 28eb2c88fc00..ad3d39df8ca6 100644 --- a/nixos/modules/virtualisation/qemu-vm.nix +++ b/nixos/modules/virtualisation/qemu-vm.nix @@ -463,14 +463,13 @@ in type = types.enum [ "host" "guest" ]; default = "host"; description = - '' + lib.mdDoc '' Controls the direction in which the ports are mapped: - - "host" means traffic from the host ports - is forwarded to the given guest port. - - - "guest" means traffic from the guest ports - is forwarded to the given host port. + - `"host"` means traffic from the host ports + is forwarded to the given guest port. + - `"guest"` means traffic from the guest ports + is forwarded to the given host port. ''; }; options.proto = mkOption {