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.

20 files changed, 49 insertions, 49 deletions

diff --git a/nixos/modules/services/desktops/accountsservice.nix b/nixos/modules/services/desktops/accountsservice.nix
index ae2ecb5ffeb..af62850acdc 100644
--- a/nixos/modules/services/desktops/accountsservice.nix
+++ b/nixos/modules/services/desktops/accountsservice.nix
@@ -19,7 +19,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable AccountsService, a DBus service for accessing
           the list of user accounts and information attached to those accounts.
         '';
diff --git a/nixos/modules/services/desktops/cpupower-gui.nix b/nixos/modules/services/desktops/cpupower-gui.nix
index f66afc0a3dc..47071aebce8 100644
--- a/nixos/modules/services/desktops/cpupower-gui.nix
+++ b/nixos/modules/services/desktops/cpupower-gui.nix
@@ -11,7 +11,7 @@ in {
         type = lib.types.bool;
         default = false;
         example = true;
-        description = ''
+        description = lib.mdDoc ''
           Enables dbus/systemd service needed by cpupower-gui.
           These services are responsible for retrieving and modifying cpu power
           saving settings.
diff --git a/nixos/modules/services/desktops/dleyna-renderer.nix b/nixos/modules/services/desktops/dleyna-renderer.nix
index 7f88605f627..daf65180b36 100644
--- a/nixos/modules/services/desktops/dleyna-renderer.nix
+++ b/nixos/modules/services/desktops/dleyna-renderer.nix
@@ -10,7 +10,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable dleyna-renderer service, a DBus service
           for handling DLNA renderers.
         '';
diff --git a/nixos/modules/services/desktops/dleyna-server.nix b/nixos/modules/services/desktops/dleyna-server.nix
index 9a131a5e700..9cbcd2a9cda 100644
--- a/nixos/modules/services/desktops/dleyna-server.nix
+++ b/nixos/modules/services/desktops/dleyna-server.nix
@@ -10,7 +10,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable dleyna-server service, a DBus service
           for handling DLNA servers.
         '';
diff --git a/nixos/modules/services/desktops/geoclue2.nix b/nixos/modules/services/desktops/geoclue2.nix
index 60a34dd6563..58bebd9bd46 100644
--- a/nixos/modules/services/desktops/geoclue2.nix
+++ b/nixos/modules/services/desktops/geoclue2.nix
@@ -16,19 +16,19 @@ let
     options = {
       desktopID = mkOption {
         type = types.str;
-        description = "Desktop ID of the application.";
+        description = lib.mdDoc "Desktop ID of the application.";
       };
 
       isAllowed = mkOption {
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether the application will be allowed access to location information.
         '';
       };
 
       isSystem = mkOption {
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Whether the application is a system component or not.
         '';
       };
@@ -36,7 +36,7 @@ let
       users = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           List of UIDs of all users for which this application is allowed location
           info access, Defaults to an empty string to allow it for all users.
         '';
@@ -67,7 +67,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable GeoClue 2 daemon, a DBus service
           that provides location information for accessing.
         '';
@@ -76,7 +76,7 @@ in
       enableDemoAgent = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to use the GeoClue demo agent. This should be
           overridden by desktop environments that provide their own
           agent.
@@ -86,7 +86,7 @@ in
       enableNmea = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to fetch location from NMEA sources on local network.
         '';
       };
@@ -94,7 +94,7 @@ in
       enable3G = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable 3G source.
         '';
       };
@@ -102,7 +102,7 @@ in
       enableCDMA = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable CDMA source.
         '';
       };
@@ -110,7 +110,7 @@ in
       enableModemGPS = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Modem-GPS source.
         '';
       };
@@ -118,7 +118,7 @@ in
       enableWifi = mkOption {
         type = types.bool;
         default = true;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable WiFi source.
         '';
       };
@@ -127,7 +127,7 @@ in
         type = types.str;
         default = "https://location.services.mozilla.com/v1/geolocate?key=geoclue";
         example = "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_KEY";
-        description = ''
+        description = lib.mdDoc ''
           The url to the wifi GeoLocation Service.
         '';
       };
@@ -135,7 +135,7 @@ in
       submitData = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to submit data to a GeoLocation Service.
         '';
       };
@@ -143,7 +143,7 @@ in
       submissionUrl = mkOption {
         type = types.str;
         default = "https://location.services.mozilla.com/v1/submit?key=geoclue";
-        description = ''
+        description = lib.mdDoc ''
           The url to submit data to a GeoLocation Service.
         '';
       };
@@ -151,7 +151,7 @@ in
       submissionNick = mkOption {
         type = types.str;
         default = "geoclue";
-        description = ''
+        description = lib.mdDoc ''
           A nickname to submit network data with.
           Must be 2-32 characters long.
         '';
@@ -167,7 +167,7 @@ in
             users = [ "300" ];
           };
         '';
-        description = ''
+        description = lib.mdDoc ''
           Specify extra settings per application.
         '';
       };
diff --git a/nixos/modules/services/desktops/gnome/at-spi2-core.nix b/nixos/modules/services/desktops/gnome/at-spi2-core.nix
index 1268a9d49b8..495ea5af987 100644
--- a/nixos/modules/services/desktops/gnome/at-spi2-core.nix
+++ b/nixos/modules/services/desktops/gnome/at-spi2-core.nix
@@ -27,12 +27,12 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable at-spi2-core, a service for the Assistive Technologies
           available on the GNOME platform.
 
           Enable this if you get the error or warning
-          <literal>The name org.a11y.Bus was not provided by any .service files</literal>.
+          `The name org.a11y.Bus was not provided by any .service files`.
         '';
       };
 
diff --git a/nixos/modules/services/desktops/gnome/evolution-data-server.nix b/nixos/modules/services/desktops/gnome/evolution-data-server.nix
index bd2242d9818..65bb75c62d2 100644
--- a/nixos/modules/services/desktops/gnome/evolution-data-server.nix
+++ b/nixos/modules/services/desktops/gnome/evolution-data-server.nix
@@ -31,7 +31,7 @@ with lib;
       plugins = mkOption {
         type = types.listOf types.package;
         default = [ ];
-        description = "Plugins for Evolution Data Server.";
+        description = lib.mdDoc "Plugins for Evolution Data Server.";
       };
     };
     programs.evolution = {
@@ -40,7 +40,7 @@ with lib;
         type = types.listOf types.package;
         default = [ ];
         example = literalExpression "[ pkgs.evolution-ews ]";
-        description = "Plugins for Evolution.";
+        description = lib.mdDoc "Plugins for Evolution.";
       };
 
     };
diff --git a/nixos/modules/services/desktops/gnome/gnome-keyring.nix b/nixos/modules/services/desktops/gnome/gnome-keyring.nix
index d821da164be..6c7e713b32d 100644
--- a/nixos/modules/services/desktops/gnome/gnome-keyring.nix
+++ b/nixos/modules/services/desktops/gnome/gnome-keyring.nix
@@ -27,7 +27,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable GNOME Keyring daemon, a service designed to
           take care of the user's security credentials,
           such as user names and passwords.
diff --git a/nixos/modules/services/desktops/gnome/gnome-online-accounts.nix b/nixos/modules/services/desktops/gnome/gnome-online-accounts.nix
index 01f7e3695cf..ed5e000cae3 100644
--- a/nixos/modules/services/desktops/gnome/gnome-online-accounts.nix
+++ b/nixos/modules/services/desktops/gnome/gnome-online-accounts.nix
@@ -27,7 +27,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable GNOME Online Accounts daemon, a service that provides
           a single sign-on framework for the GNOME desktop.
         '';
diff --git a/nixos/modules/services/desktops/gnome/gnome-online-miners.nix b/nixos/modules/services/desktops/gnome/gnome-online-miners.nix
index 5f9039f68c4..7cf1bfa1b04 100644
--- a/nixos/modules/services/desktops/gnome/gnome-online-miners.nix
+++ b/nixos/modules/services/desktops/gnome/gnome-online-miners.nix
@@ -27,7 +27,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable GNOME Online Miners, a service that
           crawls through your online content.
         '';
diff --git a/nixos/modules/services/desktops/gnome/rygel.nix b/nixos/modules/services/desktops/gnome/rygel.nix
index 7ea9778fc40..9c0faaa4885 100644
--- a/nixos/modules/services/desktops/gnome/rygel.nix
+++ b/nixos/modules/services/desktops/gnome/rygel.nix
@@ -21,10 +21,10 @@ with lib;
     services.gnome.rygel = {
       enable = mkOption {
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Rygel UPnP Mediaserver.
 
-          You will need to also allow UPnP connections in firewall, see the following <link xlink:href="https://github.com/NixOS/nixpkgs/pull/45045#issuecomment-416030795">comment</link>.
+          You will need to also allow UPnP connections in firewall, see the following [comment](https://github.com/NixOS/nixpkgs/pull/45045#issuecomment-416030795).
         '';
         type = types.bool;
       };
diff --git a/nixos/modules/services/desktops/gnome/sushi.nix b/nixos/modules/services/desktops/gnome/sushi.nix
index 3133a3a0d98..446851f434d 100644
--- a/nixos/modules/services/desktops/gnome/sushi.nix
+++ b/nixos/modules/services/desktops/gnome/sushi.nix
@@ -27,7 +27,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Sushi, a quick previewer for nautilus.
         '';
       };
diff --git a/nixos/modules/services/desktops/gnome/tracker-miners.nix b/nixos/modules/services/desktops/gnome/tracker-miners.nix
index 9351007d30b..a3c58f37420 100644
--- a/nixos/modules/services/desktops/gnome/tracker-miners.nix
+++ b/nixos/modules/services/desktops/gnome/tracker-miners.nix
@@ -27,7 +27,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Tracker miners, indexing services for Tracker
           search engine and metadata storage system.
         '';
diff --git a/nixos/modules/services/desktops/gnome/tracker.nix b/nixos/modules/services/desktops/gnome/tracker.nix
index fef399d0112..485632712f6 100644
--- a/nixos/modules/services/desktops/gnome/tracker.nix
+++ b/nixos/modules/services/desktops/gnome/tracker.nix
@@ -30,7 +30,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Tracker services, a search engine,
           search tool and metadata storage system.
         '';
diff --git a/nixos/modules/services/desktops/gsignond.nix b/nixos/modules/services/desktops/gsignond.nix
index 465acd73fa6..cf80fd75452 100644
--- a/nixos/modules/services/desktops/gsignond.nix
+++ b/nixos/modules/services/desktops/gsignond.nix
@@ -20,7 +20,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable gSignOn daemon, a DBus service
           which performs user authentication on behalf of its clients.
         '';
@@ -29,7 +29,7 @@ in
       plugins = mkOption {
         type = types.listOf types.package;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           What plugins to use with the gSignOn daemon.
         '';
       };
diff --git a/nixos/modules/services/desktops/gvfs.nix b/nixos/modules/services/desktops/gvfs.nix
index 1aa64ea37db..4aa6412aaa5 100644
--- a/nixos/modules/services/desktops/gvfs.nix
+++ b/nixos/modules/services/desktops/gvfs.nix
@@ -36,7 +36,7 @@ in
         type = types.package;
         default = pkgs.gnome.gvfs;
         defaultText = literalExpression "pkgs.gnome.gvfs";
-        description = "Which GVfs package to use.";
+        description = lib.mdDoc "Which GVfs package to use.";
       };
 
     };
diff --git a/nixos/modules/services/desktops/pipewire/pipewire.nix b/nixos/modules/services/desktops/pipewire/pipewire.nix
index dd1f5e3a018..ed64406ab6a 100644
--- a/nixos/modules/services/desktops/pipewire/pipewire.nix
+++ b/nixos/modules/services/desktops/pipewire/pipewire.nix
@@ -56,7 +56,7 @@ in {
         type = types.package;
         default = pkgs.pipewire;
         defaultText = literalExpression "pkgs.pipewire";
-        description = ''
+        description = lib.mdDoc ''
           The pipewire derivation to use.
         '';
       };
@@ -64,7 +64,7 @@ in {
       socketActivation = mkOption {
         default = true;
         type = types.bool;
-        description = ''
+        description = lib.mdDoc ''
           Automatically run pipewire when connections are made to the pipewire socket.
         '';
       };
@@ -73,7 +73,7 @@ in {
         client = mkOption {
           type = json.type;
           default = {};
-          description = ''
+          description = lib.mdDoc ''
             Configuration for pipewire clients. For details see
             https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/${cfg.package.version}/src/daemon/client.conf.in
           '';
@@ -82,7 +82,7 @@ in {
         client-rt = mkOption {
           type = json.type;
           default = {};
-          description = ''
+          description = lib.mdDoc ''
             Configuration for realtime pipewire clients. For details see
             https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/${cfg.package.version}/src/daemon/client-rt.conf.in
           '';
@@ -91,7 +91,7 @@ in {
         jack = mkOption {
           type = json.type;
           default = {};
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the pipewire daemon's jack module. For details see
             https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/${cfg.package.version}/src/daemon/jack.conf.in
           '';
@@ -100,7 +100,7 @@ in {
         pipewire = mkOption {
           type = json.type;
           default = {};
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the pipewire daemon. For details see
             https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/${cfg.package.version}/src/daemon/pipewire.conf.in
           '';
@@ -109,7 +109,7 @@ in {
         pipewire-pulse = mkOption {
           type = json.type;
           default = {};
-          description = ''
+          description = lib.mdDoc ''
             Configuration for the pipewire-pulse daemon. For details see
             https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/${cfg.package.version}/src/daemon/pipewire-pulse.conf.in
           '';
@@ -122,7 +122,7 @@ in {
           # this is for backwards compatibility
           default = cfg.alsa.enable || cfg.jack.enable || cfg.pulse.enable;
           defaultText = lib.literalExpression "config.services.pipewire.alsa.enable || config.services.pipewire.jack.enable || config.services.pipewire.pulse.enable";
-          description = "Whether to use PipeWire as the primary sound server";
+          description = lib.mdDoc "Whether to use PipeWire as the primary sound server";
         };
       };
 
@@ -142,7 +142,7 @@ in {
       systemWide = lib.mkOption {
         type = lib.types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           If true, a system-wide PipeWire service and socket is enabled
           allowing all users in the "pipewire" group to use it simultaneously.
           If false, then user units are used instead, restricting access to
diff --git a/nixos/modules/services/desktops/pipewire/wireplumber.nix b/nixos/modules/services/desktops/pipewire/wireplumber.nix
index 004392c7873..32490773b5e 100644
--- a/nixos/modules/services/desktops/pipewire/wireplumber.nix
+++ b/nixos/modules/services/desktops/pipewire/wireplumber.nix
@@ -14,14 +14,14 @@ in
         type = lib.types.bool;
         default = config.services.pipewire.enable;
         defaultText = lib.literalExpression "config.services.pipewire.enable";
-        description = "Whether to enable Wireplumber, a modular session / policy manager for PipeWire";
+        description = lib.mdDoc "Whether to enable Wireplumber, a modular session / policy manager for PipeWire";
       };
 
       package = lib.mkOption {
         type = lib.types.package;
         default = pkgs.wireplumber;
         defaultText = lib.literalExpression "pkgs.wireplumber";
-        description = "The wireplumber derivation to use.";
+        description = lib.mdDoc "The wireplumber derivation to use.";
       };
     };
   };
diff --git a/nixos/modules/services/desktops/profile-sync-daemon.nix b/nixos/modules/services/desktops/profile-sync-daemon.nix
index 6206295272f..e307c673500 100644
--- a/nixos/modules/services/desktops/profile-sync-daemon.nix
+++ b/nixos/modules/services/desktops/profile-sync-daemon.nix
@@ -9,7 +9,7 @@ in {
     enable = mkOption {
       type = bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable the Profile Sync daemon.
       '';
     };
@@ -17,7 +17,7 @@ in {
       type = str;
       default = "1h";
       example = "1h 30min";
-      description = ''
+      description = lib.mdDoc ''
         The amount of time to wait before syncing browser profiles back to the
         disk.
 
diff --git a/nixos/modules/services/desktops/telepathy.nix b/nixos/modules/services/desktops/telepathy.nix
index b5f6a5fcbcf..cdc6eb26de7 100644
--- a/nixos/modules/services/desktops/telepathy.nix
+++ b/nixos/modules/services/desktops/telepathy.nix
@@ -19,7 +19,7 @@ with lib;
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable Telepathy service, a communications framework
           that enables real-time communication via pluggable protocol backends.
         '';