nixos/*: convert internal option descriptions to MD

we'll have to do it eventually, may as well be now.
2 years ago · 9547123258
parent ef176dcf7e
commit 9547123258
60 changed files with 116 additions and 116 deletions
--- a/nixos/lib/systemd-unit-options.nix
+++ b/nixos/lib/systemd-unit-options.nix
@ -94,7 +94,7 @@ in rec {

    unit = mkOption {
      internal = true;
-      description = "The generated unit.";
+      description = lib.mdDoc "The generated unit.";
    };

  };
@ -358,7 +358,7 @@ in rec {
      jobScripts = mkOption {
        type = with types; coercedTo path singleton (listOf path);
        internal = true;
-        description = "A list of all job script derivations of this unit.";
+        description = lib.mdDoc "A list of all job script derivations of this unit.";
        default = [];
      };

--- a/nixos/modules/config/fonts/fontconfig.nix
+++ b/nixos/modules/config/fonts/fontconfig.nix
@ -259,7 +259,7 @@ in
          internal = true;
          type     = with types; listOf path;
          default  = [ ];
-          description = ''
+          description = lib.mdDoc ''
            Fontconfig configuration packages.
          '';
        };
--- a/nixos/modules/config/networking.nix
+++ b/nixos/modules/config/networking.nix
@ -141,7 +141,7 @@ in
        type = types.attrs;
        internal = true;
        default = {};
-        description = ''
+        description = lib.mdDoc ''
          Environment variables used for the network proxy.
        '';
      };
--- a/nixos/modules/config/shells-environment.nix
+++ b/nixos/modules/config/shells-environment.nix
@ -140,9 +140,9 @@ in
      example = literalExpression ''"''${pkgs.dash}/bin/dash"'';
      type = types.path;
      visible = false;
-      description = ''
+      description = lib.mdDoc ''
        The shell executable that is linked system-wide to
-        <literal>/bin/sh</literal>. Please note that NixOS assumes all
+        `/bin/sh`. Please note that NixOS assumes all
        over the place that shell to be Bash, so override the default
        setting only if you know exactly what you're doing.
      '';
--- a/nixos/modules/config/system-path.nix
+++ b/nixos/modules/config/system-path.nix
@ -132,7 +132,7 @@ in

      path = mkOption {
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          The packages you want in the boot environment.
        '';
      };
--- a/nixos/modules/config/xdg/portal.nix
+++ b/nixos/modules/config/xdg/portal.nix
@ -54,11 +54,11 @@ in
      type = types.bool;
      visible = false;
      default = false;
-      description = ''
-        Sets environment variable <literal>GTK_USE_PORTAL</literal> to <literal>1</literal>.
+      description = lib.mdDoc ''
+        Sets environment variable `GTK_USE_PORTAL` to `1`.
        This will force GTK-based programs ran outside Flatpak to respect and use XDG Desktop Portals
        for features like file chooser but it is an unsupported hack that can easily break things.
-        Defaults to <literal>false</literal> to respect its opt-in nature.
+        Defaults to `false` to respect its opt-in nature.
      '';
    };
  };
--- a/nixos/modules/hardware/device-tree.nix
+++ b/nixos/modules/hardware/device-tree.nix
@ -171,7 +171,7 @@ in
          default = null;
          type = types.nullOr types.path;
          internal = true;
-          description = ''
+          description = lib.mdDoc ''
            A path containing the result of applying `overlays` to `kernelPackage`.
          '';
        };
--- a/nixos/modules/hardware/opengl.nix
+++ b/nixos/modules/hardware/opengl.nix
@ -71,7 +71,7 @@ in
      package = mkOption {
        type = types.package;
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          The package that provides the OpenGL implementation.
        '';
      };
@ -79,9 +79,9 @@ in
      package32 = mkOption {
        type = types.package;
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          The package that provides the 32-bit OpenGL implementation on
-          64-bit systems. Used when <option>driSupport32Bit</option> is
+          64-bit systems. Used when {option}`driSupport32Bit` is
          set.
        '';
      };
@ -111,11 +111,11 @@ in
        type = types.bool;
        internal = true;
        default = false;
-        description = ''
-          Whether the <literal>LD_LIBRARY_PATH</literal> environment variable
+        description = lib.mdDoc ''
+          Whether the `LD_LIBRARY_PATH` environment variable
          should be set to the locations of driver libraries. Drivers which
          rely on overriding libraries should set this to true. Drivers which
-          support <literal>libglvnd</literal> and other dispatch libraries
+          support `libglvnd` and other dispatch libraries
          instead of overriding libraries should not set this.
        '';
      };
--- a/nixos/modules/i18n/input-method/default.nix
+++ b/nixos/modules/i18n/input-method/default.nix
@ -53,7 +53,7 @@ in
        internal = true;
        type     = types.nullOr types.path;
        default  = null;
-        description = ''
+        description = lib.mdDoc ''
          The input method method package.
        '';
      };
--- a/nixos/modules/misc/assertions.nix
+++ b/nixos/modules/misc/assertions.nix
@ -11,7 +11,7 @@ with lib;
      internal = true;
      default = [];
      example = [ { assertion = false; message = "you can't enable this for that reason"; } ];
-      description = ''
+      description = lib.mdDoc ''
        This option allows modules to express conditions that must
        hold for the evaluation of the system configuration to
        succeed, along with associated error messages for the user.
@ -23,7 +23,7 @@ with lib;
      default = [];
      type = types.listOf types.str;
      example = [ "The `foo' service is deprecated and will go away soon!" ];
-      description = ''
+      description = lib.mdDoc ''
        This option allows modules to show warnings to users during
        the evaluation of the system configuration.
      '';
--- a/nixos/modules/misc/ids.nix
+++ b/nixos/modules/misc/ids.nix
@ -19,7 +19,7 @@ in

    ids.uids = lib.mkOption {
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        The user IDs used in NixOS.
      '';
      type = types.attrsOf types.int;
@ -27,7 +27,7 @@ in

    ids.gids = lib.mkOption {
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        The group IDs used in NixOS.
      '';
      type = types.attrsOf types.int;
--- a/nixos/modules/misc/meta.nix
+++ b/nixos/modules/misc/meta.nix
@ -38,7 +38,7 @@ in
        internal = true;
        default = [];
        example = literalExpression ''[ lib.maintainers.all ]'';
-        description = ''
+        description = lib.mdDoc ''
          List of maintainers of each module.  This option should be defined at
          most once per module.
        '';
@ -48,7 +48,7 @@ in
        type = docFile;
        internal = true;
        example = "./meta.chapter.xml";
-        description = ''
+        description = lib.mdDoc ''
          Documentation prologue for the set of options of each module.  This
          option should be defined at most once per module.
        '';
@ -60,7 +60,7 @@ in
        };
        internal = true;
        default = true;
-        description = ''
+        description = lib.mdDoc ''
          Whether to include this module in the split options doc build.
          Disable if the module references `config`, `pkgs` or other module
          arguments that cannot be evaluated as constants.
--- a/nixos/modules/misc/passthru.nix
+++ b/nixos/modules/misc/passthru.nix
@ -7,7 +7,7 @@
  options = {
    passthru = lib.mkOption {
      visible = false;
-      description = ''
+      description = lib.mdDoc ''
        This attribute set will be exported as a system attribute.
        You can put whatever you want here.
      '';
--- a/nixos/modules/programs/neovim.nix
+++ b/nixos/modules/programs/neovim.nix
@ -89,7 +89,7 @@ in {
      type = types.package;
      visible = false;
      readOnly = true;
-      description = "Resulting customized neovim package.";
+      description = lib.mdDoc "Resulting customized neovim package.";
    };

    runtime = mkOption {
--- a/nixos/modules/programs/tsm-client.nix
+++ b/nixos/modules/programs/tsm-client.nix
@ -140,7 +140,7 @@ let
      type = str;
      internal = true;
      visible = false;
-      description = "Server stanza text generated from the options.";
+      description = lib.mdDoc "Server stanza text generated from the options.";
    };
    config.name = mkDefault name;
    # Client system-options file directives are explained here:
--- a/nixos/modules/security/wrappers/default.nix
+++ b/nixos/modules/security/wrappers/default.nix
@ -199,7 +199,7 @@ in
      type        = lib.types.path;
      default     = "/run/wrappers/bin";
      internal    = true;
-      description = ''
+      description = lib.mdDoc ''
        This option defines the path to the wrapper programs. It
        should not be overriden.
      '';
--- a/nixos/modules/services/audio/jack.nix
+++ b/nixos/modules/services/audio/jack.nix
@ -27,7 +27,7 @@ in {
          default = pkgs.jack2;
          defaultText = literalExpression "pkgs.jack2";
          example = literalExpression "pkgs.jack1";
-          description = ''
+          description = lib.mdDoc ''
            The JACK package to use.
          '';
        };
--- a/nixos/modules/services/cluster/hadoop/default.nix
+++ b/nixos/modules/services/cluster/hadoop/default.nix
@ -25,7 +25,7 @@ with lib;
      default = {};
      type = types.attrsOf types.anything;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        Internal option to add configs to core-site.xml based on module options
      '';
    };
@ -59,7 +59,7 @@ with lib;
      default = {};
      type = types.attrsOf types.anything;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        Internal option to add configs to hdfs-site.xml based on module options
      '';
    };
@ -134,7 +134,7 @@ with lib;
      default = {};
      type = types.attrsOf types.anything;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        Internal option to add configs to yarn-site.xml based on module options
      '';
    };
--- a/nixos/modules/services/cluster/hadoop/hbase.nix
+++ b/nixos/modules/services/cluster/hadoop/hbase.nix
@ -39,7 +39,7 @@ in
      default = {};
      type = with types; attrsOf anything;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        Internal option to add configs to hbase-site.xml based on module options
      '';
    };
--- a/nixos/modules/services/computing/slurm/slurm.nix
+++ b/nixos/modules/services/computing/slurm/slurm.nix
@ -285,7 +285,7 @@ in
          Directory created from generated config files and
          `config.${opt.extraConfigPaths}`.
        '';
-        description = ''
+        description = lib.mdDoc ''
          Path to directory with slurm config files. This option is set by default from the
          Slurm module and is meant to make the Slurm config file available to other modules.
        '';
--- a/nixos/modules/services/continuous-integration/hercules-ci-agent/common.nix
+++ b/nixos/modules/services/continuous-integration/hercules-ci-agent/common.nix
@ -236,7 +236,7 @@ in
      type = types.path;
      internal = true;
      defaultText = literalMD "generated `hercules-ci-agent.toml`";
-      description = ''
+      description = lib.mdDoc ''
        The fully assembled config file.
      '';
    };
--- a/nixos/modules/services/databases/neo4j.nix
+++ b/nixos/modules/services/databases/neo4j.nix
@ -538,7 +538,7 @@ in {
            type = types.listOf types.path;
            internal = true;
            readOnly = true;
-            description = ''
+            description = lib.mdDoc ''
              Directories of this policy that will be created automatically
              when the certificates directory is left at its default value.
              This includes all options of type path that are left at their
--- a/nixos/modules/services/databases/postgresql.nix
+++ b/nixos/modules/services/databases/postgresql.nix
@ -264,7 +264,7 @@ in
        default = "postgres";
        internal = true;
        readOnly = true;
-        description = ''
+        description = lib.mdDoc ''
          PostgreSQL superuser account to use for various operations. Internal since changing
          this value would lead to breakage while setting up databases.
        '';
--- a/nixos/modules/services/desktops/gnome/tracker.nix
+++ b/nixos/modules/services/desktops/gnome/tracker.nix
@ -40,7 +40,7 @@ in
        type = types.listOf types.package;
        default = [ ];
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          List of packages containing tracker3 subcommands.
        '';
      };
--- a/nixos/modules/services/hardware/sane.nix
+++ b/nixos/modules/services/hardware/sane.nix
@ -89,7 +89,7 @@ in
    hardware.sane.configDir = mkOption {
      type = types.str;
      internal = true;
-      description = "The value of SANE_CONFIG_DIR.";
+      description = lib.mdDoc "The value of SANE_CONFIG_DIR.";
    };

    hardware.sane.netConf = mkOption {
--- a/nixos/modules/services/hardware/udev.nix
+++ b/nixos/modules/services/hardware/udev.nix
@ -300,13 +300,13 @@ in
        type = types.listOf types.path;
        default = [];
        visible = false;
-        description = ''
-          <emphasis>This will only be used when systemd is used in stage 1.</emphasis>
+        description = lib.mdDoc ''
+          *This will only be used when systemd is used in stage 1.*

-          List of packages containing <command>udev</command> rules that will be copied to stage 1.
+          List of packages containing {command}`udev` rules that will be copied to stage 1.
          All files found in
-          <filename>«pkg»/etc/udev/rules.d</filename> and
-          <filename>«pkg»/lib/udev/rules.d</filename>
+          {file}`«pkg»/etc/udev/rules.d` and
+          {file}`«pkg»/lib/udev/rules.d`
          will be included.
        '';
      };
@ -315,8 +315,8 @@ in
        type = types.listOf types.path;
        default = [];
        visible = false;
-        description = ''
-          <emphasis>This will only be used when systemd is used in stage 1.</emphasis>
+        description = lib.mdDoc ''
+          *This will only be used when systemd is used in stage 1.*

          Packages to search for binaries that are referenced by the udev rules in stage 1.
          This list always contains /bin of the initrd.
--- a/nixos/modules/services/logging/filebeat.nix
+++ b/nixos/modules/services/logging/filebeat.nix
@ -159,27 +159,27 @@ in
                type = types.listOf json.type;
                default = [];
                internal = true;
-                description = ''
+                description = lib.mdDoc ''
                  Inputs specify how Filebeat locates and processes
-                  input data. Use <xref linkend="opt-services.filebeat.inputs"/> instead.
+                  input data. Use [](#opt-services.filebeat.inputs) instead.

-                  See <link xlink:href="https://www.elastic.co/guide/en/beats/filebeat/current/configuration-filebeat-options.html"/>.
+                  See <https://www.elastic.co/guide/en/beats/filebeat/current/configuration-filebeat-options.html>.
                '';
              };
              modules = mkOption {
                type = types.listOf json.type;
                default = [];
                internal = true;
-                description = ''
+                description = lib.mdDoc ''
                  Filebeat modules provide a quick way to get started
                  processing common log formats. They contain default
                  configurations, Elasticsearch ingest pipeline
                  definitions, and Kibana dashboards to help you
                  implement and deploy a log monitoring solution.

-                  Use <xref linkend="opt-services.filebeat.modules"/> instead.
+                  Use [](#opt-services.filebeat.modules) instead.

-                  See <link xlink:href="https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-modules.html"/>.
+                  See <https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-modules.html>.
                '';
              };
            };
--- a/nixos/modules/services/mail/mail.nix
+++ b/nixos/modules/services/mail/mail.nix
@ -14,7 +14,7 @@ with lib;
        type = types.nullOr options.security.wrappers.type.nestedTypes.elemType;
        default = null;
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          Configuration for the sendmail setuid wapper.
        '';
      };
--- a/nixos/modules/services/mail/postfix.nix
+++ b/nixos/modules/services/mail/postfix.nix
@ -140,8 +140,8 @@ let
        type = types.listOf types.str;
        default = [];
        internal = true;
-        description = ''
-          The raw configuration line for the <filename>master.cf</filename>.
+        description = lib.mdDoc ''
+          The raw configuration line for the {file}`master.cf`.
        '';
      };
    };
--- a/nixos/modules/services/misc/nix-daemon.nix
+++ b/nixos/modules/services/misc/nix-daemon.nix
@ -340,7 +340,7 @@ in
        type = types.attrs;
        internal = true;
        default = { };
-        description = "Environment variables used by Nix.";
+        description = lib.mdDoc "Environment variables used by Nix.";
      };

      nrBuildUsers = mkOption {
--- a/nixos/modules/services/misc/sourcehut/default.nix
+++ b/nixos/modules/services/misc/sourcehut/default.nix
@ -132,7 +132,7 @@ in
      internal = true;
      type = types.package;
      default = python;
-      description = ''
+      description = lib.mdDoc ''
        The python package to use. It should contain references to the *srht modules and also
        gunicorn.
      '';
--- a/nixos/modules/services/monitoring/metricbeat.nix
+++ b/nixos/modules/services/monitoring/metricbeat.nix
@ -99,10 +99,10 @@ in
              type = types.listOf settingsFormat.type;
              default = [];
              internal = true;
-              description = ''
-                The metric collecting modules. Use <xref linkend="opt-services.metricbeat.modules"/> instead.
+              description = lib.mdDoc ''
+                The metric collecting modules. Use [](#opt-services.metricbeat.modules) instead.

-                See <link xlink:href="https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-modules.html"/>.
+                See <https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-modules.html>.
              '';
            };
          };
--- a/nixos/modules/services/networking/nylon.nix
+++ b/nixos/modules/services/networking/nylon.nix
@ -139,7 +139,7 @@ in

    services.nylon = mkOption {
      default = {};
-      description = "Collection of named nylon instances";
+      description = lib.mdDoc "Collection of named nylon instances";
      type = with types; attrsOf (submodule nylonOpts);
      internal = true;
    };
--- a/nixos/modules/services/printing/cupsd.nix
+++ b/nixos/modules/services/printing/cupsd.nix
@ -167,7 +167,7 @@ in
        type = types.lines;
        internal = true;
        default = "";
-        description = ''
+        description = lib.mdDoc ''
          Additional commands executed while creating the directory
          containing the CUPS server binaries.
        '';
--- a/nixos/modules/services/system/dbus.nix
+++ b/nixos/modules/services/system/dbus.nix
@ -29,7 +29,7 @@ in
        type = types.bool;
        default = false;
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          Whether to start the D-Bus message bus daemon, which is
          required by many other system services and applications.
        '';
@ -70,7 +70,7 @@ in
        type = types.nullOr types.bool;
        default = null;
        visible = false;
-        description = ''
+        description = lib.mdDoc ''
          Removed option, do not use.
        '';
      };
--- a/nixos/modules/services/web-apps/icingaweb2/module-monitoring.nix
+++ b/nixos/modules/services/web-apps/icingaweb2/module-monitoring.nix
@ -66,7 +66,7 @@ in {
            visible = false;
            default = name;
            type = str;
-            description = "Name of this backend";
+            description = lib.mdDoc "Name of this backend";
          };

          resource = mkOption {
@ -98,7 +98,7 @@ in {
            visible = false;
            default = name;
            type = str;
-            description = "Name of this transport";
+            description = lib.mdDoc "Name of this transport";
          };

          type = mkOption {
--- a/nixos/modules/services/web-apps/nextcloud.nix
+++ b/nixos/modules/services/web-apps/nextcloud.nix
@ -529,7 +529,7 @@ in {
      default = occ;
      defaultText = literalMD "generated script";
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        The nextcloud-occ program preconfigured to target this Nextcloud instance.
      '';
    };
--- a/nixos/modules/services/x11/desktop-managers/default.nix
+++ b/nixos/modules/services/x11/desktop-managers/default.nix
@ -64,10 +64,10 @@ in
            bgSupport = true;
            start = "...";
          };
-        description = ''
+        description = lib.mdDoc ''
          Internal option used to add some common line to desktop manager
          scripts before forwarding the value to the
-          <varname>displayManager</varname>.
+          `displayManager`.
        '';
        apply = map (d: d // {
          manage = "desktop";
--- a/nixos/modules/services/x11/desktop-managers/gnome.nix
+++ b/nixos/modules/services/x11/desktop-managers/gnome.nix
@ -201,7 +201,7 @@ in
            favorite-apps=[ 'firefox.desktop', 'org.gnome.Calendar.desktop' ]
          '''
        '';
-        description = "List of desktop files to put as favorite apps into gnome-shell. These need to be installed somehow globally.";
+        description = lib.mdDoc "List of desktop files to put as favorite apps into gnome-shell. These need to be installed somehow globally.";
      };

      extraGSettingsOverrides = mkOption {
--- a/nixos/modules/services/x11/display-managers/default.nix
+++ b/nixos/modules/services/x11/display-managers/default.nix
@ -153,7 +153,7 @@ in
        internal = true;
        default = "${xorg.xauth}/bin/xauth";
        defaultText = literalExpression ''"''${pkgs.xorg.xauth}/bin/xauth"'';
-        description = "Path to the <command>xauth</command> program used by display managers.";
+        description = lib.mdDoc "Path to the {command}`xauth` program used by display managers.";
      };

      xserverBin = mkOption {
@ -252,7 +252,7 @@ in
      };

      sessionData = mkOption {
-        description = "Data exported for display managers’ convenience";
+        description = lib.mdDoc "Data exported for display managers’ convenience";
        internal = true;
        default = {};
        apply = val: {
@ -299,7 +299,7 @@ in
      importedVariables = mkOption {
        type = types.listOf (types.strMatching "[a-zA-Z_][a-zA-Z0-9_]*");
        visible = false;
-        description = ''
+        description = lib.mdDoc ''
          Environment variables to import into the systemd user environment.
        '';
      };
--- a/nixos/modules/services/x11/window-managers/default.nix
+++ b/nixos/modules/services/x11/window-managers/default.nix
@ -59,10 +59,10 @@ in
          name = "wmii";
          start = "...";
        }];
-        description = ''
+        description = lib.mdDoc ''
          Internal option used to add some common line to window manager
          scripts before forwarding the value to the
-          <varname>displayManager</varname>.
+          `displayManager`.
        '';
        apply = map (d: d // {
          manage = "window";
--- a/nixos/modules/services/x11/xserver.nix
+++ b/nixos/modules/services/x11/xserver.nix
@ -294,7 +294,7 @@ in
      drivers = mkOption {
        type = types.listOf types.attrs;
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          A list of attribute sets specifying drivers to be loaded by
          the X11 server.
        '';
--- a/nixos/modules/system/activation/activation-script.nix
+++ b/nixos/modules/system/activation/activation-script.nix
@ -139,7 +139,7 @@ in
    };

    system.dryActivationScript = mkOption {
-      description = "The shell script that is to be run when dry-activating a system.";
+      description = lib.mdDoc "The shell script that is to be run when dry-activating a system.";
      readOnly = true;
      internal = true;
      default = systemActivationScript (removeAttrs config.system.activationScripts [ "script" ]) true;
@ -199,9 +199,9 @@ in
      example = literalExpression ''"''${pkgs.busybox}/bin/env"'';
      type = types.nullOr types.path;
      visible = false;
-      description = ''
+      description = lib.mdDoc ''
        The env(1) executable that is linked system-wide to
-        <literal>/usr/bin/env</literal>.
+        `/usr/bin/env`.
      '';
    };
  };
--- a/nixos/modules/system/activation/top-level.nix
+++ b/nixos/modules/system/activation/top-level.nix
@ -207,7 +207,7 @@ in
    system.boot.loader.id = mkOption {
      internal = true;
      default = "";
-      description = ''
+      description = lib.mdDoc ''
        Id string of the used bootloader.
      '';
    };
@ -217,7 +217,7 @@ in
      default = pkgs.stdenv.hostPlatform.linux-kernel.target;
      defaultText = literalExpression "pkgs.stdenv.hostPlatform.linux-kernel.target";
      type = types.str;
-      description = ''
+      description = lib.mdDoc ''
        Name of the kernel file to be passed to the bootloader.
      '';
    };
@ -226,7 +226,7 @@ in
      internal = true;
      default = "initrd";
      type = types.str;
-      description = ''
+      description = lib.mdDoc ''
        Name of the initrd file to be passed to the bootloader.
      '';
    };
@ -238,10 +238,10 @@ in
        #             go to `true` instead of `echo`, hiding the useless path
        #             from the log.
        default = "echo 'Warning: do not know how to make this configuration bootable; please enable a boot loader.' 1>&2; true";
-        description = ''
+        description = lib.mdDoc ''
          A program that writes a bootloader installation script to the path passed in the first command line argument.

-          See <literal>nixos/modules/system/activation/switch-to-configuration.pl</literal>.
+          See `nixos/modules/system/activation/switch-to-configuration.pl`.
        '';
        type = types.unique {
          message = ''
@ -280,7 +280,7 @@ in
      type = types.lines;
      internal = true;
      default = "";
-      description = ''
+      description = lib.mdDoc ''
        This code will be added to the builder creating the system store path.
      '';
    };
--- a/nixos/modules/system/boot/binfmt.nix
+++ b/nixos/modules/system/boot/binfmt.nix
@ -256,7 +256,7 @@ in {
            interpreterSandboxPath = mkOption {
              internal = true;
              default = null;
-              description = ''
+              description = lib.mdDoc ''
                Path of the interpreter to expose in the build sandbox.
              '';
              type = types.nullOr types.path;
--- a/nixos/modules/system/boot/kernel.nix
+++ b/nixos/modules/system/boot/kernel.nix
@ -25,7 +25,7 @@ in
      default = {};
      example = literalExpression "{ debug = true; }";
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        This option allows to enable or disable certain kernel features.
        It's not API, because it's about kernel feature sets, that
        make sense for specific use cases. Mostly along with programs,
@ -173,7 +173,7 @@ in
      type = types.listOf types.path;
      internal = true;
      default = [];
-      description = ''
+      description = lib.mdDoc ''
        Tree of kernel modules.  This includes the kernel, plus modules
        built outside of the kernel.  Combine these into a single tree of
        symlinks because modprobe only supports one directory.
@ -193,7 +193,7 @@ in
      '';
      internal = true;
      type = types.listOf types.attrs;
-      description = ''
+      description = lib.mdDoc ''
        This option allows modules to specify the kernel config options that
        must be set (or unset) for the module to work. Please use the
        lib.kernelConfig functions to build list elements.
--- a/nixos/modules/system/boot/kernel_config.nix
+++ b/nixos/modules/system/boot/kernel_config.nix
@ -14,7 +14,7 @@ let
        default = null;
        internal = true;
        visible = true;
-        description = ''
+        description = lib.mdDoc ''
          Use this field for tristate kernel options expecting a "y" or "m" or "n".
        '';
      };
--- a/nixos/modules/system/boot/luksroot.nix
+++ b/nixos/modules/system/boot/luksroot.nix
@ -523,7 +523,7 @@ in
      type = types.bool;
      default = false;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        Whether to configure luks support in the initrd, when no luks
        devices are configured.
      '';
@ -563,7 +563,7 @@ in
            default = name;
            example = "luksroot";
            type = types.str;
-            description = "Name of the unencrypted device in <filename>/dev/mapper</filename>.";
+            description = lib.mdDoc "Name of the unencrypted device in {file}`/dev/mapper`.";
          };

          device = mkOption {
@ -819,7 +819,7 @@ in
            default = [];
            example = [ "_netdev" ];
            visible = false;
-            description = ''
+            description = lib.mdDoc ''
              Only used with systemd stage 1.

              Extra options to append to the last column of the generated crypttab file.
--- a/nixos/modules/system/boot/networkd.nix
+++ b/nixos/modules/system/boot/networkd.nix
@ -1824,7 +1824,7 @@ in
    };

    systemd.network.units = mkOption {
-      description = "Definition of networkd units.";
+      description = lib.mdDoc "Definition of networkd units.";
      default = {};
      internal = true;
      type = with types; attrsOf (submodule (
--- a/nixos/modules/system/boot/stage-1.nix
+++ b/nixos/modules/system/boot/stage-1.nix
@ -575,7 +575,7 @@ in
      internal = true;
      default = "";
      type = types.lines;
-      description = ''
+      description = lib.mdDoc ''
        Shell commands to be executed in the builder of the
        extra-utils derivation.  This can be used to provide
        additional utilities in the initial ramdisk.
@ -586,7 +586,7 @@ in
      internal = true;
      default = "";
      type = types.lines;
-      description = ''
+      description = lib.mdDoc ''
        Shell commands to be executed in the builder of the
        extra-utils derivation after patchelf has done its
        job.  This can be used to test additional utilities
@ -598,7 +598,7 @@ in
      internal = true;
      default = "";
      type = types.lines;
-      description = ''
+      description = lib.mdDoc ''
        Shell commands to be executed in the builder of the
        udev-rules derivation.  This can be used to add
        additional udev rules in the initial ramdisk.
@ -676,7 +676,7 @@ in
        default = false;
        type = types.bool;
        description =
-          ''
+          lib.mdDoc ''
            Whether the bootloader setup runs append-initrd-secrets.
            If not, any needed secrets must be copied into the initrd
            and thus added to the store.
--- a/nixos/modules/system/boot/systemd/user.nix
+++ b/nixos/modules/system/boot/systemd/user.nix
@ -97,7 +97,7 @@ in {
      default = [];
      type = types.listOf types.str;
      example = [];
-      description = ''
+      description = lib.mdDoc ''
        Additional units shipped with systemd that should be enabled for per-user systemd instances.
      '';
      internal = true;
--- a/nixos/modules/tasks/filesystems.nix
+++ b/nixos/modules/tasks/filesystems.nix
@ -223,7 +223,7 @@ in
    system.fsPackages = mkOption {
      internal = true;
      default = [ ];
-      description = "Packages supplying file system mounters and checkers.";
+      description = lib.mdDoc "Packages supplying file system mounters and checkers.";
    };

    boot.supportedFilesystems = mkOption {
@ -237,7 +237,7 @@ in
      default = {};
      type = types.attrsOf (types.submodule coreFileSystemOpts);
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        Special filesystems that are mounted very early during boot.
      '';
    };
--- a/nixos/modules/tasks/lvm.nix
+++ b/nixos/modules/tasks/lvm.nix
@ -10,7 +10,7 @@ in {
      default = pkgs.lvm2;
      internal = true;
      defaultText = literalExpression "pkgs.lvm2";
-      description = ''
+      description = lib.mdDoc ''
        This option allows you to override the LVM package that's used on the system
        (udev rules, tmpfiles, systemd services).
        Defaults to pkgs.lvm2, pkgs.lvm2_dmeventd if dmeventd or pkgs.lvm2_vdo if vdo is enabled.
--- a/nixos/modules/testing/service-runner.nix
+++ b/nixos/modules/testing/service-runner.nix
@ -107,7 +107,7 @@ let
  opts = { config, name, ... }: {
    options.runner = mkOption {
    internal = true;
-    description = ''
+    description = lib.mdDoc ''
        A script that runs the service outside of systemd,
        useful for testing or for using NixOS services outside
        of NixOS.
--- a/nixos/modules/virtualisation/amazon-options.nix
+++ b/nixos/modules/virtualisation/amazon-options.nix
@ -8,7 +8,7 @@ in {
        enable = lib.mkOption {
          default = false;
          internal = true;
-          description = ''
+          description = lib.mdDoc ''
            Whether the EC2 instance uses a ZFS root.
          '';
        };
@ -44,7 +44,7 @@ in {
      hvm = lib.mkOption {
        default = lib.versionAtLeast config.system.stateVersion "17.03";
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          Whether the EC2 instance is a HVM instance.
        '';
      };
@ -52,7 +52,7 @@ in {
        default = pkgs.stdenv.hostPlatform.isAarch64;
        defaultText = literalExpression "pkgs.stdenv.hostPlatform.isAarch64";
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          Whether the EC2 instance is using EFI.
        '';
      };
--- a/nixos/modules/virtualisation/cri-o.nix
+++ b/nixos/modules/virtualisation/cri-o.nix
@ -72,7 +72,7 @@ in
      type = types.package;
      default = crioPackage;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        The final CRI-O package (including extra packages).
      '';
    };
@ -80,7 +80,7 @@ in
    networkDir = mkOption {
      type = types.nullOr types.path;
      default = null;
-      description = "Override the network_dir option.";
+      description = lib.mdDoc "Override the network_dir option.";
      internal = true;
    };

--- a/nixos/modules/virtualisation/openstack-options.nix
+++ b/nixos/modules/virtualisation/openstack-options.nix
@ -9,7 +9,7 @@ in
        enable = lib.mkOption {
          default = false;
          internal = true;
-          description = ''
+          description = lib.mdDoc ''
            Whether the OpenStack instance uses a ZFS root.
          '';
        };
@ -47,7 +47,7 @@ in
        default = pkgs.stdenv.hostPlatform.isAarch64;
        defaultText = literalExpression "pkgs.stdenv.hostPlatform.isAarch64";
        internal = true;
-        description = ''
+        description = lib.mdDoc ''
          Whether the instance is using EFI.
        '';
      };
--- a/nixos/modules/virtualisation/podman/default.nix
+++ b/nixos/modules/virtualisation/podman/default.nix
@ -114,7 +114,7 @@ in
      type = types.package;
      default = podmanPackage;
      internal = true;
-      description = ''
+      description = lib.mdDoc ''
        The final Podman package (including extra packages).
      '';
    };
--- a/nixos/modules/virtualisation/qemu-vm.nix
+++ b/nixos/modules/virtualisation/qemu-vm.nix
@ -570,7 +570,7 @@ in
        type = types.str;
        default = "";
        internal = true;
-        description = "Primary IP address used in /etc/hosts.";
+        description = lib.mdDoc "Primary IP address used in /etc/hosts.";
      };

    virtualisation.qemu = {
--- a/nixos/tests/common/resolver.nix
+++ b/nixos/tests/common/resolver.nix
@ -10,15 +10,15 @@
    type = lib.types.bool;
    default = true;
    internal = true;
-    description = ''
+    description = lib.mdDoc ''
      Whether to enable the resolver that automatically discovers zone in the
      test network.

-      This option is <literal>true</literal> by default, because the module
+      This option is `true` by default, because the module
      defining this option needs to be explicitly imported.

      The reason this option exists is for the
-      <filename>nixos/tests/common/acme/server</filename> module, which
+      {file}`nixos/tests/common/acme/server` module, which
      needs that option to disable the resolver once the user has set its own
      resolver.
    '';