lib/modules: convert option description to MD

1 files changed, 43 insertions, 77 deletions

diff --git a/lib/modules.nix b/lib/modules.nix
index 7f1646e9b8b..659f1dd75dd 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -163,84 +163,50 @@ rec {
             # TODO: Change the type of this option to a submodule with a
             # freeformType, so that individual arguments can be documented
             # separately
-            description = ''
+            description = lib.mdDoc ''
               Additional arguments passed to each module in addition to ones
-              like <literal>lib</literal>, <literal>config</literal>,
-              and <literal>pkgs</literal>, <literal>modulesPath</literal>.
-              </para>
-              <para>
+              like `lib`, `config`,
+              and `pkgs`, `modulesPath`.
+
               This option is also available to all submodules. Submodules do not
               inherit args from their parent module, nor do they provide args to
               their parent module or sibling submodules. The sole exception to
-              this is the argument <literal>name</literal> which is provided by
+              this is the argument `name` which is provided by
               parent modules to a submodule and contains the attribute name
               the submodule is bound to, or a unique generated name if it is
               not bound to an attribute.
-              </para>
-              <para>
+
               Some arguments are already passed by default, of which the
-              following <emphasis>cannot</emphasis> be changed with this option:
-              <itemizedlist>
-               <listitem>
-                <para>
-                 <varname>lib</varname>: The nixpkgs library.
-                </para>
-               </listitem>
-               <listitem>
-                <para>
-                 <varname>config</varname>: The results of all options after merging the values from all modules together.
-                </para>
-               </listitem>
-               <listitem>
-                <para>
-                 <varname>options</varname>: The options declared in all modules.
-                </para>
-               </listitem>
-               <listitem>
-                <para>
-                 <varname>specialArgs</varname>: The <literal>specialArgs</literal> argument passed to <literal>evalModules</literal>.
-                </para>
-               </listitem>
-               <listitem>
-                <para>
-                 All attributes of <varname>specialArgs</varname>
-                </para>
-                <para>
-                 Whereas option values can generally depend on other option values
-                 thanks to laziness, this does not apply to <literal>imports</literal>, which
-                 must be computed statically before anything else.
-                </para>
-                <para>
-                 For this reason, callers of the module system can provide <literal>specialArgs</literal>
-                 which are available during import resolution.
-                </para>
-                <para>
-                 For NixOS, <literal>specialArgs</literal> includes
-                 <varname>modulesPath</varname>, which allows you to import
-                 extra modules from the nixpkgs package tree without having to
-                 somehow make the module aware of the location of the
-                 <literal>nixpkgs</literal> or NixOS directories.
-              <programlisting>
-              { modulesPath, ... }: {
-                imports = [
-                  (modulesPath + "/profiles/minimal.nix")
-                ];
-              }
-              </programlisting>
-                </para>
-               </listitem>
-              </itemizedlist>
-              </para>
-              <para>
+              following *cannot* be changed with this option:
+              - {var}`lib`: The nixpkgs library.
+              - {var}`config`: The results of all options after merging the values from all modules together.
+              - {var}`options`: The options declared in all modules.
+              - {var}`specialArgs`: The `specialArgs` argument passed to `evalModules`.
+              - All attributes of {var}`specialArgs`
+
+                Whereas option values can generally depend on other option values
+                thanks to laziness, this does not apply to `imports`, which
+                must be computed statically before anything else.
+
+                For this reason, callers of the module system can provide `specialArgs`
+                which are available during import resolution.
+
+                For NixOS, `specialArgs` includes
+                {var}`modulesPath`, which allows you to import
+                extra modules from the nixpkgs package tree without having to
+                somehow make the module aware of the location of the
+                `nixpkgs` or NixOS directories.
+                ```
+                { modulesPath, ... }: {
+                  imports = [
+                    (modulesPath + "/profiles/minimal.nix")
+                  ];
+                }
+                ```
+
               For NixOS, the default value for this option includes at least this argument:
-              <itemizedlist>
-               <listitem>
-                <para>
-                 <varname>pkgs</varname>: The nixpkgs package set according to
-                 the <option>nixpkgs.pkgs</option> option.
-                </para>
-               </listitem>
-              </itemizedlist>
+              - {var}`pkgs`: The nixpkgs package set according to
+                the {option}`nixpkgs.pkgs` option.
             '';
           };
 
@@ -248,21 +214,21 @@ rec {
             type = types.bool;
             internal = true;
             default = true;
-            description = "Whether to check whether all option definitions have matching declarations.";
+            description = lib.mdDoc "Whether to check whether all option definitions have matching declarations.";
           };
 
           _module.freeformType = mkOption {
             type = types.nullOr types.optionType;
             internal = true;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               If set, merge all definitions that don't have an associated option
               together using this type. The result then gets combined with the
-              values of all declared options to produce the final <literal>
-              config</literal> value.
+              values of all declared options to produce the final `
+              config` value.
 
-              If this is <literal>null</literal>, definitions without an option
-              will throw an error unless <option>_module.check</option> is
+              If this is `null`, definitions without an option
+              will throw an error unless {option}`_module.check` is
               turned off.
             '';
           };
@@ -270,7 +236,7 @@ rec {
           _module.specialArgs = mkOption {
             readOnly = true;
             internal = true;
-            description = ''
+            description = lib.mdDoc ''
               Externally provided module arguments that can't be modified from
               within a configuration, but can be used in module imports.
             '';
@@ -1167,7 +1133,7 @@ rec {
     {
       options = setAttrByPath from (mkOption {
         inherit visible;
-        description = "Alias of <option>${showOption to}</option>.";
+        description = lib.mdDoc "Alias of {option}`${showOption to}`.";
         apply = x: use (toOf config);
       } // optionalAttrs (toType != null) {
         type = toType;