ilyakooo0/nixpkgs
1
0
Fork 0
mirror of https://github.com/ilyakooo0/nixpkgs.git synced 2024-12-27 22:03:54 +03:00
Code Issues Projects Releases Wiki Activity

lib/modules: convert option description to MD

Browse Source
This commit is contained in:
pennae 2022-08-30 14:15:36 +02:00
parent f2ea09ecbe
commit e04a09082e
2 changed files with 44 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
lib/modules.nix
View File

@ -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>
<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 Whereas option values can generally depend on other option values
thanks to laziness, this does not apply to <literal>imports</literal>, which thanks to laziness, this does not apply to `imports`, which
must be computed statically before anything else. must be computed statically before anything else.
</para>
<para> For this reason, callers of the module system can provide `specialArgs`
For this reason, callers of the module system can provide <literal>specialArgs</literal>
which are available during import resolution. which are available during import resolution.
</para>
<para> For NixOS, `specialArgs` includes
For NixOS, <literal>specialArgs</literal> includes {var}`modulesPath`, which allows you to import
<varname>modulesPath</varname>, which allows you to import
extra modules from the nixpkgs package tree without having to extra modules from the nixpkgs package tree without having to
somehow make the module aware of the location of the somehow make the module aware of the location of the
<literal>nixpkgs</literal> or NixOS directories. `nixpkgs` or NixOS directories.
<programlisting> ```
{ modulesPath, ... }: { { modulesPath, ... }: {
imports = [ imports = [
(modulesPath + "/profiles/minimal.nix") (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;

2
lib/options.nix
View File

@ -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');