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

@@ -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

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.

nixos/modules/services/backup/restic.nix

@@ -182,11 +182,11 @@ in
         pruneOpts = mkOption {
           type = types.listOf types.str;
           default = [ ];
-          description = ''
+          description = lib.mdDoc ''
-            A list of options (--keep-* et al.) for 'restic forget
+            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"

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 <link linkend="opt-services.logrotate.paths._name_.priority">priority</link> 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 <link linkend="opt-services.logrotate.settings">logrotate settings</link>.
+          This setting has been deprecated in favor of [logrotate settings](#opt-services.logrotate.settings).
         '';
         example = literalExpression ''
           {

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

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»</option>.
+          {option}`services.nginx.virtualHosts.«name»`.
         '';
       };
 

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`";

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*_min` and
-            "cat /sys/devices/platform/applesmc.768/fan*_max" respectively.
+            `cat /sys/devices/platform/applesmc.768/fan*_max` respectively.
             Setting to null implies using default value from applesmc.
           '';
         };

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" ];

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.
 

nixos/modules/services/networking/bitlbee.nix

@@ -59,9 +59,9 @@ in
       interface = mkOption {
         type = types.str;
         default = "127.0.0.1";
-        description = ''
+        description = lib.mdDoc ''
-          The interface the BitlBee deamon will be listening to.  If `127.0.0.1',
+          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
+          only clients on the local host can connect to it; if `0.0.0.0`, clients
           can access it from any network interface.
         '';
       };

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 <link xlink:href="http://probably.loki/wiki/index.php?title=Exit_Nodes"/> for
+                  See <http://probably.loki/wiki/index.php?title=Exit_Nodes> for
                   a list of exit nodes.
                 '';
               };

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
+          <https://github.com/NixOS/nixpkgs/issues/24318#issuecomment-289216273>
           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].
+          libvirt. For information on how the two firewalls interact, see
-
+          <https://wiki.nftables.org/wiki-nftables/index.php/Troubleshooting#Question_4._How_do_nftables_and_iptables_interact_when_used_on_the_same_system.3F>.
-          [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
         '';
     };
     networking.nftables.ruleset = mkOption {

nixos/modules/services/networking/quassel.nix

@@ -47,9 +47,9 @@ in
       interfaces = mkOption {
         type = types.listOf types.str;
         default = [ "127.0.0.1" ];
-        description = ''
+        description = lib.mdDoc ''
-          The interfaces the Quassel daemon will be listening to.  If `[ 127.0.0.1 ]',
+          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
+          only clients on the local host can connect to it; if `[ 0.0.0.0 ]`, clients
           can access it from any network interface.
         '';
       };

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 <link xlink:href="https://manual.seafile.com/config/seahub_settings_py/"/>
+        Refer to <https://manual.seafile.com/config/seahub_settings_py/>
         for all available options.
       '';
     };

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

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`

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
-        <literal>systembus-notify</literal> running as your user, which this
+        `systembus-notify` running as your user, which this
-        option handles by enabling <option>services.systembus-notify</option>.
+        option handles by enabling {option}`services.systembus-notify`.
 
-        See <link xlink:href="https://github.com/rfjakob/earlyoom#notifications">README</link> for details.
+        See [README](https://github.com/rfjakob/earlyoom#notifications) for details.
       '';
     };
 

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 {

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 {

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:
 
-                - <literal>"host"</literal> means traffic from the host ports
+                - `"host"` means traffic from the host ports
-                is forwarded to the given guest port.
+                  is forwarded to the given guest port.
-
+                - `"guest"` means traffic from the guest ports
-                - <literal>"guest"</literal> means traffic from the guest ports
+                  is forwarded to the given host port.
-                is forwarded to the given host port.
               '';
           };
           options.proto = mkOption {