From e04a09082e33d444c245e1d5859b37ace25f54a9 Mon Sep 17 00:00:00 2001 From: pennae Date: Tue, 30 Aug 2022 14:15:36 +0200 Subject: [PATCH] lib/modules: convert option description to MD --- lib/modules.nix | 120 +++++++++++++++++------------------------------- lib/options.nix | 2 +- 2 files changed, 44 insertions(+), 78 deletions(-) diff --git a/lib/modules.nix b/lib/modules.nix index 7f1646e9b8bc..659f1dd75dd1 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 lib, config, - and pkgs, modulesPath. - - + 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 name 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. - - + Some arguments are already passed by default, of which the - following cannot be changed with this option: - - - - lib: The nixpkgs library. - - - - - config: The results of all options after merging the values from all modules together. - - - - - options: The options declared in all modules. - - - - - specialArgs: The specialArgs argument passed to evalModules. - - - - - All attributes of 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 - 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") - ]; - } - - - - - - + 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: - - - - pkgs: The nixpkgs package set according to - the option. - - - + - {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 - config value. + values of all declared options to produce the final ` + config` value. - If this is null, definitions without an option - will throw an error unless 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 ."; + 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 b6376796dbac..a56e579ab84d 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');