diff options
-rw-r--r-- | lib/modules.nix | 120 | ||||
-rw-r--r-- | lib/options.nix | 2 |
2 files changed, 44 insertions, 78 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; diff --git a/lib/options.nix b/lib/options.nix index b6376796dba..a56e579ab84 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -137,7 +137,7 @@ rec { let default' = if !isList default then [ default ] else default; in mkOption { type = lib.types.package; - description = "The ${name} package to use."; + description = lib.mdDoc "The ${name} package to use."; default = attrByPath default' (throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs; defaultText = literalExpression ("pkgs." + concatStringsSep "." default'); |