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