From 90c82bfee7bf4eb8f9d529f3bb61ea31a004e4cb Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Sat, 14 Dec 2019 00:15:23 +0100 Subject: [PATCH] nixos/docs: Add docs for types.submoduleWith --- nixos/doc/manual/development/option-types.xml | 56 ++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml index 8fcbb627342b..1ec7e3efad71 100644 --- a/nixos/doc/manual/development/option-types.xml +++ b/nixos/doc/manual/development/option-types.xml @@ -259,12 +259,66 @@ A set of sub options o. o can be an attribute set or a function returning an attribute set. Submodules are used in composed types to - create modular options. Submodule are detailed in + create modular options. This is equivalent to + types.submoduleWith { modules = toList o; shorthandOnlyDefinesConfig = true; }. + Submodules are detailed in . + + + types.submoduleWith { + modules, + specialArgs ? {}, + shorthandOnlyDefinesConfig ? false } + + + + Like types.submodule, but more flexible and with better defaults. + It has parameters + + + modules + A list of modules to use by default for this submodule type. This gets combined + with all option definitions to build the final list of modules that will be included. + + Only options defined with this argument are included in rendered documentation. + + + + specialArgs + An attribute set of extra arguments to be passed to the module functions. + The option _module.args should be used instead + for most arguments since it allows overriding. specialArgs should only be + used for arguments that can't go through the module fixed-point, because of + infinite recursion or other problems. An example is overriding the + lib argument, because lib itself is used + to define _module.args, which makes using + _module.args to define it impossible. + + + shorthandOnlyDefinesConfig + Whether definitions of this type should default to the config + section of a module (see ) if it is an attribute + set. Enabling this only has a benefit when the submodule defines an option named + config or options. In such a case it would + allow the option to be set with the-submodule.config = "value" + instead of requiring the-submodule.config.config = "value". + This is because only when modules don't set the + config or options keys, all keys are interpreted + as option definitions in the config section. Enabling this option + implicitly puts all attributes in the config section. + + + With this option enabled, defining a non-config section requires + using a function: the-submodule = { ... }: { options = { ... }; }. + + + + +