treewide: automatically md-convert option descriptions

the conversion procedure is simple:

 - find all things that look like options, ie calls to either `mkOption`
   or `lib.mkOption` that take an attrset. remember the attrset as the
   option
 - for all options, find a `description` attribute who's value is not a
   call to `mdDoc` or `lib.mdDoc`
 - textually convert the entire value of the attribute to MD with a few
   simple regexes (the set from mdize-module.sh)
 - if the change produced a change in the manual output, discard
 - if the change kept the manual unchanged, add some text to the
   description to make sure we've actually found an option. if the
   manual changes this time, keep the converted description

this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.

7 files changed, 72 insertions, 72 deletions

diff --git a/nixos/modules/services/torrent/deluge.nix b/nixos/modules/services/torrent/deluge.nix
index cb0da9e83b42e..3f4cd2ff6e01d 100644
--- a/nixos/modules/services/torrent/deluge.nix
+++ b/nixos/modules/services/torrent/deluge.nix
@@ -42,7 +42,7 @@ in {
         openFilesLimit = mkOption {
           default = openFilesLimit;
           type = types.either types.int types.str;
-          description = ''
+          description = lib.mdDoc ''
             Number of files to allow deluged to open.
           '';
         };
@@ -60,12 +60,12 @@ in {
               listen_ports = [ ${toString listenPortsDefault} ];
             }
           '';
-          description = ''
+          description = lib.mdDoc ''
             Deluge core configuration for the core.conf file. Only has an effect
-            when <option>services.deluge.declarative</option> is set to
-            <literal>true</literal>. String values must be quoted, integer and
+            when {option}`services.deluge.declarative` is set to
+            `true`. String values must be quoted, integer and
             boolean values must not. See
-            <link xlink:href="https://git.deluge-torrent.org/deluge/tree/deluge/core/preferencesmanager.py#n41"/>
+            <https://git.deluge-torrent.org/deluge/tree/deluge/core/preferencesmanager.py#n41>
             for the availaible options.
           '';
         };
@@ -73,12 +73,12 @@ in {
         declarative = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Whether to use a declarative deluge configuration.
-            Only if set to <literal>true</literal>, the options
-            <option>services.deluge.config</option>,
-            <option>services.deluge.openFirewall</option> and
-            <option>services.deluge.authFile</option> will be
+            Only if set to `true`, the options
+            {option}`services.deluge.config`,
+            {option}`services.deluge.openFirewall` and
+            {option}`services.deluge.authFile` will be
             applied.
           '';
         };
@@ -86,15 +86,15 @@ in {
         openFirewall = mkOption {
           default = false;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Whether to open the firewall for the ports in
-            <option>services.deluge.config.listen_ports</option>. It only takes effet if
-            <option>services.deluge.declarative</option> is set to
-            <literal>true</literal>.
+            {option}`services.deluge.config.listen_ports`. It only takes effet if
+            {option}`services.deluge.declarative` is set to
+            `true`.
 
             It does NOT apply to the daemon port nor the web UI port. To access those
             ports secuerly check the documentation
-            <link xlink:href="https://dev.deluge-torrent.org/wiki/UserGuide/ThinClient#CreateSSHTunnel"/>
+            <https://dev.deluge-torrent.org/wiki/UserGuide/ThinClient#CreateSSHTunnel>
             or use a VPN or configure certificates for deluge.
           '';
         };
@@ -102,7 +102,7 @@ in {
         dataDir = mkOption {
           type = types.path;
           default = "/var/lib/deluge";
-          description = ''
+          description = lib.mdDoc ''
             The directory where deluge will create files.
           '';
         };
@@ -110,13 +110,13 @@ in {
         authFile = mkOption {
           type = types.path;
           example = "/run/keys/deluge-auth";
-          description = ''
+          description = lib.mdDoc ''
             The file managing the authentication for deluge, the format of this
             file is straightforward, each line contains a
             username:password:level tuple in plaintext. It only has an effect
-            when <option>services.deluge.declarative</option> is set to
-            <literal>true</literal>.
-            See <link xlink:href="https://dev.deluge-torrent.org/wiki/UserGuide/Authentication"/> for
+            when {option}`services.deluge.declarative` is set to
+            `true`.
+            See <https://dev.deluge-torrent.org/wiki/UserGuide/Authentication> for
             more informations.
           '';
         };
@@ -124,7 +124,7 @@ in {
         user = mkOption {
           type = types.str;
           default = "deluge";
-          description = ''
+          description = lib.mdDoc ''
             User account under which deluge runs.
           '';
         };
@@ -132,7 +132,7 @@ in {
         group = mkOption {
           type = types.str;
           default = "deluge";
-          description = ''
+          description = lib.mdDoc ''
             Group under which deluge runs.
           '';
         };
@@ -140,7 +140,7 @@ in {
         extraPackages = mkOption {
           type = types.listOf types.package;
           default = [];
-          description = ''
+          description = lib.mdDoc ''
             Extra packages available at runtime to enable Deluge's plugins. For example,
             extraction utilities are required for the built-in "Extractor" plugin.
             This always contains unzip, gnutar, xz and bzip2.
@@ -150,7 +150,7 @@ in {
         package = mkOption {
           type = types.package;
           example = literalExpression "pkgs.deluge-2_x";
-          description = ''
+          description = lib.mdDoc ''
             Deluge package to use.
           '';
         };
@@ -162,7 +162,7 @@ in {
         port = mkOption {
           type = types.port;
           default = 8112;
-          description = ''
+          description = lib.mdDoc ''
             Deluge web UI port.
           '';
         };
@@ -170,7 +170,7 @@ in {
         openFirewall = mkOption {
           type = types.bool;
           default = false;
-          description = ''
+          description = lib.mdDoc ''
             Open ports in the firewall for deluge web daemon
           '';
         };
diff --git a/nixos/modules/services/torrent/flexget.nix b/nixos/modules/services/torrent/flexget.nix
index e500e02d861b2..17d77bfae5fa9 100644
--- a/nixos/modules/services/torrent/flexget.nix
+++ b/nixos/modules/services/torrent/flexget.nix
@@ -20,34 +20,34 @@ in {
         default = "deluge";
         example = "some_user";
         type = types.str;
-        description = "The user under which to run flexget.";
+        description = lib.mdDoc "The user under which to run flexget.";
       };
 
       homeDir = mkOption {
         default = "/var/lib/deluge";
         example = "/home/flexget";
         type = types.path;
-        description = "Where files live.";
+        description = lib.mdDoc "Where files live.";
       };
 
       interval = mkOption {
         default = "10m";
         example = "1h";
         type = types.str;
-        description = "When to perform a <command>flexget</command> run. See <command>man 7 systemd.time</command> for the format.";
+        description = lib.mdDoc "When to perform a {command}`flexget` run. See {command}`man 7 systemd.time` for the format.";
       };
 
       systemScheduler = mkOption {
         default = true;
         example = false;
         type = types.bool;
-        description = "When true, execute the runs via the flexget-runner.timer. If false, you have to specify the settings yourself in the YML file.";
+        description = lib.mdDoc "When true, execute the runs via the flexget-runner.timer. If false, you have to specify the settings yourself in the YML file.";
       };
 
       config = mkOption {
         default = "";
         type = types.lines;
-        description = "The YAML configuration for FlexGet.";
+        description = lib.mdDoc "The YAML configuration for FlexGet.";
       };
     };
   };
diff --git a/nixos/modules/services/torrent/magnetico.nix b/nixos/modules/services/torrent/magnetico.nix
index 3dd7b1ece768b..11f1c71e3f818 100644
--- a/nixos/modules/services/torrent/magnetico.nix
+++ b/nixos/modules/services/torrent/magnetico.nix
@@ -49,7 +49,7 @@ in {
       type = types.str;
       default = "0.0.0.0";
       example = "1.2.3.4";
-      description = ''
+      description = lib.mdDoc ''
         Address to be used for indexing DHT nodes.
       '';
     };
@@ -57,17 +57,17 @@ in {
     crawler.port = mkOption {
       type = types.port;
       default = 0;
-      description = ''
+      description = lib.mdDoc ''
         Port to be used for indexing DHT nodes.
         This port should be added to
-        <option>networking.firewall.allowedTCPPorts</option>.
+        {option}`networking.firewall.allowedTCPPorts`.
       '';
     };
 
     crawler.maxNeighbors = mkOption {
       type = types.ints.positive;
       default = 1000;
-      description = ''
+      description = lib.mdDoc ''
         Maximum number of simultaneous neighbors of an indexer.
         Be careful changing this number: high values can very
         easily cause your network to be congested or even crash
@@ -78,7 +78,7 @@ in {
     crawler.maxLeeches = mkOption {
       type = types.ints.positive;
       default = 200;
-      description = ''
+      description = lib.mdDoc ''
         Maximum number of simultaneous leeches.
       '';
     };
@@ -86,7 +86,7 @@ in {
     crawler.extraOptions = mkOption {
       type = types.listOf types.str;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         Extra command line arguments to pass to magneticod.
       '';
     };
@@ -95,7 +95,7 @@ in {
       type = types.str;
       default = "localhost";
       example = "1.2.3.4";
-      description = ''
+      description = lib.mdDoc ''
         Address the web interface will listen to.
       '';
     };
@@ -103,7 +103,7 @@ in {
     web.port = mkOption {
       type = types.port;
       default = 8080;
-      description = ''
+      description = lib.mdDoc ''
         Port the web interface will listen to.
       '';
     };
@@ -159,7 +159,7 @@ in {
     web.extraOptions = mkOption {
       type = types.listOf types.str;
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         Extra command line arguments to pass to magneticow.
       '';
     };
diff --git a/nixos/modules/services/torrent/opentracker.nix b/nixos/modules/services/torrent/opentracker.nix
index d76d61dfe8594..20b3d35a603a9 100644
--- a/nixos/modules/services/torrent/opentracker.nix
+++ b/nixos/modules/services/torrent/opentracker.nix
@@ -9,7 +9,7 @@ in {
 
     package = mkOption {
       type = types.package;
-      description = ''
+      description = lib.mdDoc ''
         opentracker package to use
       '';
       default = pkgs.opentracker;
@@ -18,7 +18,7 @@ in {
 
     extraOptions = mkOption {
       type = types.separatedString " ";
-      description = ''
+      description = lib.mdDoc ''
         Configuration Arguments for opentracker
         See https://erdgeist.org/arts/software/opentracker/ for all params
       '';
diff --git a/nixos/modules/services/torrent/peerflix.nix b/nixos/modules/services/torrent/peerflix.nix
index 821c829f6b4af..ea74d0f8b9c48 100644
--- a/nixos/modules/services/torrent/peerflix.nix
+++ b/nixos/modules/services/torrent/peerflix.nix
@@ -19,19 +19,19 @@ in {
 
   options.services.peerflix = {
     enable = mkOption {
-      description = "Whether to enable peerflix service.";
+      description = lib.mdDoc "Whether to enable peerflix service.";
       default = false;
       type = types.bool;
     };
 
     stateDir = mkOption {
-      description = "Peerflix state directory.";
+      description = lib.mdDoc "Peerflix state directory.";
       default = "/var/lib/peerflix";
       type = types.path;
     };
 
     downloadDir = mkOption {
-      description = "Peerflix temporary download directory.";
+      description = lib.mdDoc "Peerflix temporary download directory.";
       default = "${cfg.stateDir}/torrents";
       defaultText = literalExpression ''"''${config.${opt.stateDir}}/torrents"'';
       type = types.path;
diff --git a/nixos/modules/services/torrent/rtorrent.nix b/nixos/modules/services/torrent/rtorrent.nix
index 759dcfe2e6c50..a805e09923ff0 100644
--- a/nixos/modules/services/torrent/rtorrent.nix
+++ b/nixos/modules/services/torrent/rtorrent.nix
@@ -14,7 +14,7 @@ in {
     dataDir = mkOption {
       type = types.str;
       default = "/var/lib/rtorrent";
-      description = ''
+      description = lib.mdDoc ''
         The directory where rtorrent stores its data files.
       '';
     };
@@ -23,7 +23,7 @@ in {
       type = types.str;
       default = "${cfg.dataDir}/download";
       defaultText = literalExpression ''"''${config.${opt.dataDir}}/download"'';
-      description = ''
+      description = lib.mdDoc ''
         Where to put downloaded files.
       '';
     };
@@ -31,7 +31,7 @@ in {
     user = mkOption {
       type = types.str;
       default = "rtorrent";
-      description = ''
+      description = lib.mdDoc ''
         User account under which rtorrent runs.
       '';
     };
@@ -39,7 +39,7 @@ in {
     group = mkOption {
       type = types.str;
       default = "rtorrent";
-      description = ''
+      description = lib.mdDoc ''
         Group under which rtorrent runs.
       '';
     };
@@ -48,7 +48,7 @@ in {
       type = types.package;
       default = pkgs.rtorrent;
       defaultText = literalExpression "pkgs.rtorrent";
-      description = ''
+      description = lib.mdDoc ''
         The rtorrent package to use.
       '';
     };
@@ -56,7 +56,7 @@ in {
     port = mkOption {
       type = types.port;
       default = 50000;
-      description = ''
+      description = lib.mdDoc ''
         The rtorrent port.
       '';
     };
@@ -64,8 +64,8 @@ in {
     openFirewall = mkOption {
       type = types.bool;
       default = false;
-      description = ''
-        Whether to open the firewall for the port in <option>services.rtorrent.port</option>.
+      description = lib.mdDoc ''
+        Whether to open the firewall for the port in {option}`services.rtorrent.port`.
       '';
     };
 
@@ -73,7 +73,7 @@ in {
       type = types.str;
       readOnly = true;
       default = "/run/rtorrent/rpc.sock";
-      description = ''
+      description = lib.mdDoc ''
         RPC socket path.
       '';
     };
@@ -81,8 +81,8 @@ in {
     configText = mkOption {
       type = types.lines;
       default = "";
-      description = ''
-        The content of <filename>rtorrent.rc</filename>. The <link xlink:href="https://rtorrent-docs.readthedocs.io/en/latest/cookbook.html#modernized-configuration-template">modernized configuration template</link> with the values specified in this module will be prepended using mkBefore. You can use mkForce to overwrite the config completly.
+      description = lib.mdDoc ''
+        The content of {file}`rtorrent.rc`. The [modernized configuration template](https://rtorrent-docs.readthedocs.io/en/latest/cookbook.html#modernized-configuration-template) with the values specified in this module will be prepended using mkBefore. You can use mkForce to overwrite the config completly.
       '';
     };
   };
diff --git a/nixos/modules/services/torrent/transmission.nix b/nixos/modules/services/torrent/transmission.nix
index d12d8aa239802..9777964386c96 100644
--- a/nixos/modules/services/torrent/transmission.nix
+++ b/nixos/modules/services/torrent/transmission.nix
@@ -34,12 +34,12 @@ in
         accessible to users in the "transmission" group'';
 
       settings = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Settings whose options overwrite fields in
-          <literal>.config/transmission-daemon/settings.json</literal>
+          `.config/transmission-daemon/settings.json`
           (each time the service starts).
 
-          See <link xlink:href="https://github.com/transmission/transmission/wiki/Editing-Configuration-Files">Transmission's Wiki</link>
+          See [Transmission's Wiki](https://github.com/transmission/transmission/wiki/Editing-Configuration-Files)
           for documentation of settings not explicitely covered by this module.
         '';
         default = {};
@@ -49,7 +49,7 @@ in
             type = types.path;
             default = "${cfg.home}/${downloadsDir}";
             defaultText = literalExpression ''"''${config.${opt.home}}/${downloadsDir}"'';
-            description = "Directory where to download torrents.";
+            description = lib.mdDoc "Directory where to download torrents.";
           };
           options.incomplete-dir = mkOption {
             type = types.path;
@@ -72,12 +72,12 @@ in
           options.message-level = mkOption {
             type = types.ints.between 0 3;
             default = 2;
-            description = "Set verbosity of transmission messages.";
+            description = lib.mdDoc "Set verbosity of transmission messages.";
           };
           options.peer-port = mkOption {
             type = types.port;
             default = 51413;
-            description = "The peer port to listen for incoming connections.";
+            description = lib.mdDoc "The peer port to listen for incoming connections.";
           };
           options.peer-port-random-high = mkOption {
             type = types.port;
@@ -98,7 +98,7 @@ in
           options.peer-port-random-on-start = mkOption {
             type = types.bool;
             default = false;
-            description = "Randomize the peer port.";
+            description = lib.mdDoc "Randomize the peer port.";
           };
           options.rpc-bind-address = mkOption {
             type = types.str;
@@ -112,7 +112,7 @@ in
           options.rpc-port = mkOption {
             type = types.port;
             default = 9091;
-            description = "The RPC port to listen to.";
+            description = lib.mdDoc "The RPC port to listen to.";
           };
           options.script-torrent-done-enabled = mkOption {
             type = types.bool;
@@ -126,12 +126,12 @@ in
           options.script-torrent-done-filename = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = "Executable to be run at torrent completion.";
+            description = lib.mdDoc "Executable to be run at torrent completion.";
           };
           options.umask = mkOption {
             type = types.int;
             default = 2;
-            description = ''
+            description = lib.mdDoc ''
               Sets transmission's file mode creation mask.
               See the umask(2) manpage for more information.
               Users who want their saved torrents to be world-writable
@@ -143,15 +143,15 @@ in
           options.utp-enabled = mkOption {
             type = types.bool;
             default = true;
-            description = ''
-              Whether to enable <link xlink:href="http://en.wikipedia.org/wiki/Micro_Transport_Protocol">Micro Transport Protocol (µTP)</link>.
+            description = lib.mdDoc ''
+              Whether to enable [Micro Transport Protocol (µTP)](http://en.wikipedia.org/wiki/Micro_Transport_Protocol).
             '';
           };
           options.watch-dir = mkOption {
             type = types.path;
             default = "${cfg.home}/${watchDir}";
             defaultText = literalExpression ''"''${config.${opt.home}}/${watchDir}"'';
-            description = "Watch a directory for torrent files and add them to transmission.";
+            description = lib.mdDoc "Watch a directory for torrent files and add them to transmission.";
           };
           options.watch-dir-enabled = mkOption {
             type = types.bool;
@@ -200,13 +200,13 @@ in
       user = mkOption {
         type = types.str;
         default = "transmission";
-        description = "User account under which Transmission runs.";
+        description = lib.mdDoc "User account under which Transmission runs.";
       };
 
       group = mkOption {
         type = types.str;
         default = "transmission";
-        description = "Group account under which Transmission runs.";
+        description = lib.mdDoc "Group account under which Transmission runs.";
       };
 
       credentialsFile = mkOption {
@@ -224,7 +224,7 @@ in
         type = types.listOf types.str;
         default = [];
         example = [ "--log-debug" ];
-        description = ''
+        description = lib.mdDoc ''
           Extra flags passed to the transmission command in the service definition.
         '';
       };