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.

1 files changed, 33 insertions, 33 deletions

diff --git a/nixos/modules/services/home-automation/home-assistant.nix b/nixos/modules/services/home-automation/home-assistant.nix
index 2cff5051c757f..175560f0cc8a3 100644
--- a/nixos/modules/services/home-automation/home-assistant.nix
+++ b/nixos/modules/services/home-automation/home-assistant.nix
@@ -82,7 +82,7 @@ in {
     configDir = mkOption {
       default = "/var/lib/hass";
       type = types.path;
-      description = "The config directory, where your <filename>configuration.yaml</filename> is located.";
+      description = lib.mdDoc "The config directory, where your {file}`configuration.yaml` is located.";
     };
 
     extraComponents = mkOption {
@@ -107,10 +107,10 @@ in {
           "wled"
         ]
       '';
-      description = ''
-        List of <link xlink:href="https://www.home-assistant.io/integrations/">components</link> that have their dependencies included in the package.
+      description = lib.mdDoc ''
+        List of [components](https://www.home-assistant.io/integrations/) that have their dependencies included in the package.
 
-        The component name can be found in the URL, for example <literal>https://www.home-assistant.io/integrations/ffmpeg/</literal> would map to <literal>ffmpeg</literal>.
+        The component name can be found in the URL, for example `https://www.home-assistant.io/integrations/ffmpeg/` would map to `ffmpeg`.
       '';
     };
 
@@ -148,7 +148,7 @@ in {
               type = types.nullOr types.str;
               default = null;
               example = "Home";
-              description = ''
+              description = lib.mdDoc ''
                 Name of the location where Home Assistant is running.
               '';
             };
@@ -157,7 +157,7 @@ in {
               type = types.nullOr (types.either types.float types.str);
               default = null;
               example = 52.3;
-              description = ''
+              description = lib.mdDoc ''
                 Latitude of your location required to calculate the time the sun rises and sets.
               '';
             };
@@ -166,7 +166,7 @@ in {
               type = types.nullOr (types.either types.float types.str);
               default = null;
               example = 4.9;
-              description = ''
+              description = lib.mdDoc ''
                 Longitude of your location required to calculate the time the sun rises and sets.
               '';
             };
@@ -175,7 +175,7 @@ in {
               type = types.nullOr (types.enum [ "metric" "imperial" ]);
               default = null;
               example = "metric";
-              description = ''
+              description = lib.mdDoc ''
                 The unit system to use. This also sets temperature_unit, Celsius for Metric and Fahrenheit for Imperial.
               '';
             };
@@ -184,8 +184,8 @@ in {
               type = types.nullOr (types.enum [ "C" "F" ]);
               default = null;
               example = "C";
-              description = ''
-                Override temperature unit set by unit_system. <literal>C</literal> for Celsius, <literal>F</literal> for Fahrenheit.
+              description = lib.mdDoc ''
+                Override temperature unit set by unit_system. `C` for Celsius, `F` for Fahrenheit.
               '';
             };
 
@@ -196,8 +196,8 @@ in {
                 config.time.timeZone or null
               '';
               example = "Europe/Amsterdam";
-              description = ''
-                Pick your time zone from the column TZ of Wikipedia’s <link xlink:href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">list of tz database time zones</link>.
+              description = lib.mdDoc ''
+                Pick your time zone from the column TZ of Wikipedia’s [list of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
               '';
             };
           };
@@ -211,7 +211,7 @@ in {
                 "::"
               ];
               example = "::1";
-              description = ''
+              description = lib.mdDoc ''
                 Only listen to incoming requests on specific IP/host. The default listed assumes support for IPv4 and IPv6.
               '';
             };
@@ -219,7 +219,7 @@ in {
             server_port = mkOption {
               default = 8123;
               type = types.port;
-              description = ''
+              description = lib.mdDoc ''
                 The port on which to listen.
               '';
             };
@@ -238,8 +238,8 @@ in {
                 else "storage";
               '';
               example = "yaml";
-              description = ''
-                In what mode should the main Lovelace panel be, <literal>yaml</literal> or <literal>storage</literal> (UI managed).
+              description = lib.mdDoc ''
+                In what mode should the main Lovelace panel be, `yaml` or `storage` (UI managed).
               '';
             };
           };
@@ -262,14 +262,14 @@ in {
           feedreader.urls = [ "https://nixos.org/blogs.xml" ];
         }
       '';
-      description = ''
-        Your <filename>configuration.yaml</filename> as a Nix attribute set.
+      description = lib.mdDoc ''
+        Your {file}`configuration.yaml` as a Nix attribute set.
 
-        YAML functions like <link xlink:href="https://www.home-assistant.io/docs/configuration/secrets/">secrets</link>
+        YAML functions like [secrets](https://www.home-assistant.io/docs/configuration/secrets/)
         can be passed as a string and will be unquoted automatically.
 
-        Unless this option is explicitly set to <literal>null</literal>
-        we assume your <filename>configuration.yaml</filename> is
+        Unless this option is explicitly set to `null`
+        we assume your {file}`configuration.yaml` is
         managed through this module and thereby overwritten on startup.
       '';
     };
@@ -277,12 +277,12 @@ in {
     configWritable = mkOption {
       default = false;
       type = types.bool;
-      description = ''
-        Whether to make <filename>configuration.yaml</filename> writable.
+      description = lib.mdDoc ''
+        Whether to make {file}`configuration.yaml` writable.
 
         This will allow you to edit it from Home Assistant's web interface.
 
-        This only has an effect if <option>config</option> is set.
+        This only has an effect if {option}`config` is set.
         However, bear in mind that it will be overwritten at every start of the service.
       '';
     };
@@ -304,23 +304,23 @@ in {
           } ];
         }
       '';
-      description = ''
-        Your <filename>ui-lovelace.yaml</filename> as a Nix attribute set.
-        Setting this option will automatically set <literal>lovelace.mode</literal> to <literal>yaml</literal>.
+      description = lib.mdDoc ''
+        Your {file}`ui-lovelace.yaml` as a Nix attribute set.
+        Setting this option will automatically set `lovelace.mode` to `yaml`.
 
-        Beware that setting this option will delete your previous <filename>ui-lovelace.yaml</filename>
+        Beware that setting this option will delete your previous {file}`ui-lovelace.yaml`
       '';
     };
 
     lovelaceConfigWritable = mkOption {
       default = false;
       type = types.bool;
-      description = ''
-        Whether to make <filename>ui-lovelace.yaml</filename> writable.
+      description = lib.mdDoc ''
+        Whether to make {file}`ui-lovelace.yaml` writable.
 
         This will allow you to edit it from Home Assistant's web interface.
 
-        This only has an effect if <option>lovelaceConfig</option> is set.
+        This only has an effect if {option}`lovelaceConfig` is set.
         However, bear in mind that it will be overwritten at every start of the service.
       '';
     };
@@ -347,7 +347,7 @@ in {
           ];
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         The Home Assistant package to use.
       '';
     };
@@ -355,7 +355,7 @@ in {
     openFirewall = mkOption {
       default = false;
       type = types.bool;
-      description = "Whether to open the firewall for the specified port.";
+      description = lib.mdDoc "Whether to open the firewall for the specified port.";
     };
   };