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, 39 insertions, 39 deletions

diff --git a/nixos/modules/services/development/blackfire.nix b/nixos/modules/services/development/blackfire.nix
index 8564aabc6a37..6b71e59d4bd5 100644
--- a/nixos/modules/services/development/blackfire.nix
+++ b/nixos/modules/services/development/blackfire.nix
@@ -18,7 +18,7 @@ in {
     services.blackfire-agent = {
       enable = lib.mkEnableOption "Blackfire profiler agent";
       settings = lib.mkOption {
-        description = ''
+        description = lib.mdDoc ''
           See https://blackfire.io/docs/up-and-running/configuration/agent
         '';
         type = lib.types.submodule {
@@ -27,7 +27,7 @@ in {
           options = {
             server-id = lib.mkOption {
               type = lib.types.str;
-              description = ''
+              description = lib.mdDoc ''
                 Sets the server id used to authenticate with Blackfire
 
                 You can find your personal server-id at https://blackfire.io/my/settings/credentials
@@ -36,7 +36,7 @@ in {
 
             server-token = lib.mkOption {
               type = lib.types.str;
-              description = ''
+              description = lib.mdDoc ''
                 Sets the server token used to authenticate with Blackfire
 
                 You can find your personal server-token at https://blackfire.io/my/settings/credentials
diff --git a/nixos/modules/services/development/bloop.nix b/nixos/modules/services/development/bloop.nix
index c1180a8bbdd4..27da76a74432 100644
--- a/nixos/modules/services/development/bloop.nix
+++ b/nixos/modules/services/development/bloop.nix
@@ -17,7 +17,7 @@ in {
         "-J-XX:MaxInlineLevel=20"
         "-J-XX:+UseParallelGC"
       ];
-      description = ''
+      description = lib.mdDoc ''
         Specifies additional command line argument to pass to bloop
         java process.
       '';
@@ -26,7 +26,7 @@ in {
     install = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to install a user service for the Bloop server.
 
         The service must be manually started for each user with
diff --git a/nixos/modules/services/development/distccd.nix b/nixos/modules/services/development/distccd.nix
index 9f6d5c813c45..7a8e780c3eb6 100644
--- a/nixos/modules/services/development/distccd.nix
+++ b/nixos/modules/services/development/distccd.nix
@@ -14,7 +14,7 @@ in
         type = types.listOf types.str;
         default = [ "127.0.0.1" ];
         example = [ "127.0.0.1" "192.168.0.0/24" "10.0.0.0/24" ];
-        description = ''
+        description = lib.mdDoc ''
           Client IPs which are allowed to connect to distccd in CIDR notation.
 
           Anyone who can connect to the distccd server can run arbitrary
@@ -26,7 +26,7 @@ in
       jobTimeout = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Maximum duration, in seconds, of a single compilation request.
         '';
       };
@@ -34,7 +34,7 @@ in
       logLevel = mkOption {
         type = types.nullOr (types.enum [ "critical" "error" "warning" "notice" "info" "debug" ]);
         default = "warning";
-        description = ''
+        description = lib.mdDoc ''
           Set the minimum severity of error that will be included in the log
           file. Useful if you only want to see error messages rather than an
           entry for each connection.
@@ -44,7 +44,7 @@ in
       maxJobs = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Maximum number of tasks distccd should execute at any time.
         '';
       };
@@ -53,7 +53,7 @@ in
       nice = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Niceness of the compilation tasks.
         '';
       };
@@ -61,7 +61,7 @@ in
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Opens the specified TCP port for distcc.
         '';
       };
@@ -70,7 +70,7 @@ in
         type = types.package;
         default = pkgs.distcc;
         defaultText = literalExpression "pkgs.distcc";
-        description = ''
+        description = lib.mdDoc ''
           The distcc package to use.
         '';
       };
@@ -78,7 +78,7 @@ in
       port = mkOption {
         type = types.port;
         default = 3632;
-        description = ''
+        description = lib.mdDoc ''
           The TCP port which distccd will listen on.
         '';
       };
@@ -88,7 +88,7 @@ in
         port = mkOption {
           type = types.port;
           default = 3633;
-          description = ''
+          description = lib.mdDoc ''
             The TCP port which the distccd statistics HTTP server will listen
             on.
           '';
@@ -98,7 +98,7 @@ in
       zeroconf = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to register via mDNS/DNS-SD
         '';
       };
diff --git a/nixos/modules/services/development/hoogle.nix b/nixos/modules/services/development/hoogle.nix
index 7c2a1c8e1624..399ffccabfc6 100644
--- a/nixos/modules/services/development/hoogle.nix
+++ b/nixos/modules/services/development/hoogle.nix
@@ -19,7 +19,7 @@ in {
     port = mkOption {
       type = types.port;
       default = 8080;
-      description = ''
+      description = lib.mdDoc ''
         Port number Hoogle will be listening to.
       '';
     };
@@ -39,7 +39,7 @@ in {
     };
 
     haskellPackages = mkOption {
-      description = "Which haskell package set to use.";
+      description = lib.mdDoc "Which haskell package set to use.";
       type = types.attrs;
       default = pkgs.haskellPackages;
       defaultText = literalExpression "pkgs.haskellPackages";
@@ -47,13 +47,13 @@ in {
 
     home = mkOption {
       type = types.str;
-      description = "Url for hoogle logo";
+      description = lib.mdDoc "Url for hoogle logo";
       default = "https://hoogle.haskell.org";
     };
 
     host = mkOption {
       type = types.str;
-      description = "Set the host to bind on.";
+      description = lib.mdDoc "Set the host to bind on.";
       default = "127.0.0.1";
     };
   };
diff --git a/nixos/modules/services/development/lorri.nix b/nixos/modules/services/development/lorri.nix
index bda63518bfd9..a82b3f57f8e8 100644
--- a/nixos/modules/services/development/lorri.nix
+++ b/nixos/modules/services/development/lorri.nix
@@ -18,7 +18,7 @@ in {
       package = lib.mkOption {
         default = pkgs.lorri;
         type = lib.types.package;
-        description = ''
+        description = lib.mdDoc ''
           The lorri package to use.
         '';
         defaultText = lib.literalExpression "pkgs.lorri";
diff --git a/nixos/modules/services/development/rstudio-server/default.nix b/nixos/modules/services/development/rstudio-server/default.nix
index cd903c7e55bf..74a7cd2f4e57 100644
--- a/nixos/modules/services/development/rstudio-server/default.nix
+++ b/nixos/modules/services/development/rstudio-server/default.nix
@@ -26,7 +26,7 @@ in
     serverWorkingDir = mkOption {
       type = types.str;
       default = "/var/lib/rstudio-server";
-      description = ''
+      description = lib.mdDoc ''
         Default working directory for server (server-working-dir in rserver.conf).
       '';
     };
@@ -34,7 +34,7 @@ in
     listenAddr = mkOption {
       type = types.str;
       default = "127.0.0.1";
-      description = ''
+      description = lib.mdDoc ''
         Address to listen on (www-address in rserver.conf).
       '';
     };
@@ -44,7 +44,7 @@ in
       default = pkgs.rstudio-server;
       defaultText = literalExpression "pkgs.rstudio-server";
       example = literalExpression "pkgs.rstudioServerWrapper.override { packages = [ pkgs.rPackages.ggplot2 ]; }";
-      description = ''
+      description = lib.mdDoc ''
         Rstudio server package to use. Can be set to rstudioServerWrapper to provide packages.
       '';
     };
@@ -52,7 +52,7 @@ in
     rserverExtraConfig = mkOption {
       type = types.str;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Extra contents for rserver.conf.
       '';
     };
@@ -60,7 +60,7 @@ in
     rsessionExtraConfig = mkOption {
       type = types.str;
       default = "";
-      description = ''
+      description = lib.mdDoc ''
         Extra contents for resssion.conf.
       '';
     };
diff --git a/nixos/modules/services/development/zammad.nix b/nixos/modules/services/development/zammad.nix
index d457a6071873..503f54aee2c7 100644
--- a/nixos/modules/services/development/zammad.nix
+++ b/nixos/modules/services/development/zammad.nix
@@ -34,13 +34,13 @@ in
         type = types.package;
         default = pkgs.zammad;
         defaultText = literalExpression "pkgs.zammad";
-        description = "Zammad package to use.";
+        description = lib.mdDoc "Zammad package to use.";
       };
 
       dataDir = mkOption {
         type = types.path;
         default = "/var/lib/zammad";
-        description = ''
+        description = lib.mdDoc ''
           Path to a folder that will contain Zammad working directory.
         '';
       };
@@ -49,25 +49,25 @@ in
         type = types.str;
         default = "127.0.0.1";
         example = "192.168.23.42";
-        description = "Host address.";
+        description = lib.mdDoc "Host address.";
       };
 
       openPorts = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to open firewall ports for Zammad";
+        description = lib.mdDoc "Whether to open firewall ports for Zammad";
       };
 
       port = mkOption {
         type = types.port;
         default = 3000;
-        description = "Web service port.";
+        description = lib.mdDoc "Web service port.";
       };
 
       websocketPort = mkOption {
         type = types.port;
         default = 6042;
-        description = "Websocket service port.";
+        description = lib.mdDoc "Websocket service port.";
       };
 
       database = {
@@ -75,7 +75,7 @@ in
           type = types.enum [ "PostgreSQL" "MySQL" ];
           default = "PostgreSQL";
           example = "MySQL";
-          description = "Database engine to use.";
+          description = lib.mdDoc "Database engine to use.";
         };
 
         host = mkOption {
@@ -90,7 +90,7 @@ in
               MySQL = "localhost";
             }.''${config.services.zammad.database.type};
           '';
-          description = ''
+          description = lib.mdDoc ''
             Database host address.
           '';
         };
@@ -98,13 +98,13 @@ in
         port = mkOption {
           type = types.nullOr types.port;
           default = null;
-          description = "Database port. Use <literal>null</literal> for default port.";
+          description = lib.mdDoc "Database port. Use `null` for default port.";
         };
 
         name = mkOption {
           type = types.str;
           default = "zammad";
-          description = ''
+          description = lib.mdDoc ''
             Database name.
           '';
         };
@@ -112,22 +112,22 @@ in
         user = mkOption {
           type = types.nullOr types.str;
           default = "zammad";
-          description = "Database user.";
+          description = lib.mdDoc "Database user.";
         };
 
         passwordFile = mkOption {
           type = types.nullOr types.path;
           default = null;
           example = "/run/keys/zammad-dbpassword";
-          description = ''
-            A file containing the password for <option>services.zammad.database.user</option>.
+          description = lib.mdDoc ''
+            A file containing the password for {option}`services.zammad.database.user`.
           '';
         };
 
         createLocally = mkOption {
           type = types.bool;
           default = true;
-          description = "Whether to create a local database automatically.";
+          description = lib.mdDoc "Whether to create a local database automatically.";
         };
 
         settings = mkOption {