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.

5 files changed, 42 insertions, 42 deletions

diff --git a/nixos/modules/services/video/epgstation/default.nix b/nixos/modules/services/video/epgstation/default.nix
index 191f6eb52e57..51f71389263c 100644
--- a/nixos/modules/services/video/epgstation/default.nix
+++ b/nixos/modules/services/video/epgstation/default.nix
@@ -84,17 +84,17 @@ in
       default = pkgs.epgstation;
       type = lib.types.package;
       defaultText = lib.literalExpression "pkgs.epgstation";
-      description = "epgstation package to use";
+      description = lib.mdDoc "epgstation package to use";
     };
 
     usePreconfiguredStreaming = lib.mkOption {
       type = lib.types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Use preconfigured default streaming options.
 
         Upstream defaults:
-        <link xlink:href="https://github.com/l3tnun/EPGStation/blob/master/config/config.yml.template"/>
+        <https://github.com/l3tnun/EPGStation/blob/master/config/config.yml.template>
       '';
     };
 
@@ -118,7 +118,7 @@ in
       name = lib.mkOption {
         type = lib.types.str;
         default = "epgstation";
-        description = ''
+        description = lib.mdDoc ''
           Name of the MySQL database that holds EPGStation's data.
         '';
       };
@@ -126,9 +126,9 @@ in
       passwordFile = lib.mkOption {
         type = lib.types.path;
         example = "/run/keys/epgstation-db-password";
-        description = ''
+        description = lib.mdDoc ''
           A file containing the password for the database named
-          <option>database.name</option>.
+          {option}`database.name`.
         '';
       };
     };
@@ -144,11 +144,11 @@ in
     # configure them according to their needs. In these cases, the value in the
     # upstream template configuration should serve as a "good enough" default.
     settings = lib.mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Options to add to config.yml.
 
         Documentation:
-        <link xlink:href="https://github.com/l3tnun/EPGStation/blob/master/doc/conf-manual.md"/>
+        <https://github.com/l3tnun/EPGStation/blob/master/doc/conf-manual.md>
       '';
 
       default = { };
@@ -163,7 +163,7 @@ in
         options.port = lib.mkOption {
           type = lib.types.port;
           default = 20772;
-          description = ''
+          description = lib.mdDoc ''
             HTTP port for EPGStation to listen on.
           '';
         };
@@ -172,9 +172,9 @@ in
           type = lib.types.port;
           default = cfg.settings.port + 1;
           defaultText = lib.literalExpression "config.${opt.settings}.port + 1";
-          description = ''
+          description = lib.mdDoc ''
             Socket.io port for EPGStation to listen on. It is valid to share
-            ports with <option>${opt.settings}.port</option>.
+            ports with {option}`${opt.settings}.port`.
           '';
         };
 
@@ -182,9 +182,9 @@ in
           type = lib.types.port;
           default = cfg.settings.socketioPort;
           defaultText = lib.literalExpression "config.${opt.settings}.socketioPort";
-          description = ''
+          description = lib.mdDoc ''
             Socket.io port that the web client is going to connect to. This may
-            be different from <option>${opt.settings}.socketioPort</option> if
+            be different from {option}`${opt.settings}.socketioPort` if
             EPGStation is hidden behind a reverse proxy.
           '';
         };
@@ -196,13 +196,13 @@ in
             "http+unix://''${lib.replaceStrings ["/"] ["%2F"] config.${option}}"
           '';
           example = "http://localhost:40772";
-          description = "URL to connect to Mirakurun.";
+          description = lib.mdDoc "URL to connect to Mirakurun.";
         };
 
         options.encodeProcessNum = lib.mkOption {
           type = lib.types.ints.positive;
           default = 4;
-          description = ''
+          description = lib.mdDoc ''
             The maximum number of processes that EPGStation would allow to run
             at the same time for encoding or streaming videos.
           '';
@@ -211,7 +211,7 @@ in
         options.concurrentEncodeNum = lib.mkOption {
           type = lib.types.ints.positive;
           default = 1;
-          description = ''
+          description = lib.mdDoc ''
             The maximum number of encoding jobs that EPGStation would run at the
             same time.
           '';
@@ -219,7 +219,7 @@ in
 
         options.encode = lib.mkOption {
           type = with lib.types; listOf attrs;
-          description = "Encoding presets for recorded videos.";
+          description = lib.mdDoc "Encoding presets for recorded videos.";
           default = [
             {
               name = "H.264";
diff --git a/nixos/modules/services/video/mirakurun.nix b/nixos/modules/services/video/mirakurun.nix
index 35303b2332c6..90119361afab 100644
--- a/nixos/modules/services/video/mirakurun.nix
+++ b/nixos/modules/services/video/mirakurun.nix
@@ -29,8 +29,8 @@ in
         port = mkOption {
           type = with types; nullOr port;
           default = 40772;
-          description = ''
-            Port to listen on. If <literal>null</literal>, it won't listen on
+          description = lib.mdDoc ''
+            Port to listen on. If `null`, it won't listen on
             any port.
           '';
         };
@@ -54,8 +54,8 @@ in
         unixSocket = mkOption {
           type = with types; nullOr path;
           default = "/var/run/mirakurun/mirakurun.sock";
-          description = ''
-            Path to unix socket to listen on. If <literal>null</literal>, it
+          description = lib.mdDoc ''
+            Path to unix socket to listen on. If `null`, it
             won't listen on any unix sockets.
           '';
         };
@@ -63,7 +63,7 @@ in
         allowSmartCardAccess = mkOption {
           type = types.bool;
           default = true;
-          description = ''
+          description = lib.mdDoc ''
             Install polkit rules to allow Mirakurun to access smart card readers
             which is commonly used along with tuner devices.
           '';
@@ -78,11 +78,11 @@ in
               overflowTimeLimit = 30000;
             };
           '';
-          description = ''
+          description = lib.mdDoc ''
             Options for server.yml.
 
             Documentation:
-            <link xlink:href="https://github.com/Chinachu/Mirakurun/blob/master/doc/Configuration.md"/>
+            <https://github.com/Chinachu/Mirakurun/blob/master/doc/Configuration.md>
           '';
         };
 
@@ -98,12 +98,12 @@ in
               }
             ];
           '';
-          description = ''
+          description = lib.mdDoc ''
             Options which are added to tuners.yml. If none is specified, it will
             automatically be generated at runtime.
 
             Documentation:
-            <link xlink:href="https://github.com/Chinachu/Mirakurun/blob/master/doc/Configuration.md"/>
+            <https://github.com/Chinachu/Mirakurun/blob/master/doc/Configuration.md>
           '';
         };
 
@@ -119,12 +119,12 @@ in
               }
             ];
           '';
-          description = ''
+          description = lib.mdDoc ''
             Options which are added to channels.yml. If none is specified, it
             will automatically be generated at runtime.
 
             Documentation:
-            <link xlink:href="https://github.com/Chinachu/Mirakurun/blob/master/doc/Configuration.md"/>
+            <https://github.com/Chinachu/Mirakurun/blob/master/doc/Configuration.md>
           '';
         };
       };
diff --git a/nixos/modules/services/video/replay-sorcery.nix b/nixos/modules/services/video/replay-sorcery.nix
index abe7202a4a86..f3cecfc248cf 100644
--- a/nixos/modules/services/video/replay-sorcery.nix
+++ b/nixos/modules/services/video/replay-sorcery.nix
@@ -19,13 +19,13 @@ in
       autoStart = mkOption {
         type = bool;
         default = false;
-        description = "Automatically start ReplaySorcery when graphical-session.target starts.";
+        description = lib.mdDoc "Automatically start ReplaySorcery when graphical-session.target starts.";
       };
 
       settings = mkOption {
         type = attrsOf (oneOf [ str int ]);
         default = {};
-        description = "System-wide configuration for ReplaySorcery (/etc/replay-sorcery.conf).";
+        description = lib.mdDoc "System-wide configuration for ReplaySorcery (/etc/replay-sorcery.conf).";
         example = literalExpression ''
           {
             videoInput = "hwaccel"; # requires `services.replay-sorcery.enableSysAdminCapability = true`
diff --git a/nixos/modules/services/video/rtsp-simple-server.nix b/nixos/modules/services/video/rtsp-simple-server.nix
index 644b1945a1ec..db6f0441bbf1 100644
--- a/nixos/modules/services/video/rtsp-simple-server.nix
+++ b/nixos/modules/services/video/rtsp-simple-server.nix
@@ -13,9 +13,9 @@ in
       enable = mkEnableOption "RTSP Simple Server";
 
       settings = mkOption {
-        description = ''
+        description = lib.mdDoc ''
           Settings for rtsp-simple-server.
-          Read more at <link xlink:href="https://github.com/aler9/rtsp-simple-server/blob/main/rtsp-simple-server.yml"/>
+          Read more at <https://github.com/aler9/rtsp-simple-server/blob/main/rtsp-simple-server.yml>
         '';
         type = format.type;
 
@@ -40,7 +40,7 @@ in
 
       env = mkOption {
         type = with types; attrsOf anything;
-        description = "Extra environment variables for RTSP Simple Server";
+        description = lib.mdDoc "Extra environment variables for RTSP Simple Server";
         default = {};
         example = {
           RTSP_CONFKEY = "mykey";
diff --git a/nixos/modules/services/video/unifi-video.nix b/nixos/modules/services/video/unifi-video.nix
index 11d9fe305470..fcc3cb02a1b0 100644
--- a/nixos/modules/services/video/unifi-video.nix
+++ b/nixos/modules/services/video/unifi-video.nix
@@ -98,7 +98,7 @@ in
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether or not to enable the unifi-video service.
       '';
     };
@@ -107,7 +107,7 @@ in
       type = types.package;
       default = pkgs.jre8;
       defaultText = literalExpression "pkgs.jre8";
-      description = ''
+      description = lib.mdDoc ''
         The JRE package to use. Check the release notes to ensure it is supported.
       '';
     };
@@ -116,7 +116,7 @@ in
       type = types.package;
       default = pkgs.unifi-video;
       defaultText = literalExpression "pkgs.unifi-video";
-      description = ''
+      description = lib.mdDoc ''
         The unifi-video package to use.
       '';
     };
@@ -125,7 +125,7 @@ in
       type = types.package;
       default = pkgs.mongodb-4_0;
       defaultText = literalExpression "pkgs.mongodb";
-      description = ''
+      description = lib.mdDoc ''
         The mongodb package to use.
       '';
     };
@@ -133,7 +133,7 @@ in
     logDir = mkOption {
       type = types.str;
       default = "${stateDir}/logs";
-      description = ''
+      description = lib.mdDoc ''
         Where to store the logs.
       '';
     };
@@ -141,7 +141,7 @@ in
     dataDir = mkOption {
       type = types.str;
       default = "${stateDir}/data";
-      description = ''
+      description = lib.mdDoc ''
         Where to store the database and other data.
       '';
     };
@@ -149,7 +149,7 @@ in
     openFirewall = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether or not to open the required ports on the firewall.
       '';
     };
@@ -158,7 +158,7 @@ in
       type = types.nullOr types.int;
       default = 1024;
       example = 4096;
-      description = ''
+      description = lib.mdDoc ''
         Set the maximimum heap size for the JVM in MB.
       '';
     };
@@ -167,7 +167,7 @@ in
       type = types.path;
       default = "${cfg.dataDir}/unifi-video.pid";
       defaultText = literalExpression ''"''${config.${opt.dataDir}}/unifi-video.pid"'';
-      description = "Location of unifi-video pid file.";
+      description = lib.mdDoc "Location of unifi-video pid file.";
     };
 
   };