lib/modules: Document _module.args

Documents the _module.args option, motivated by many usages in Flakes,
especially with the deprecation of extraArgs
(78ada83361)

The documentation rendering for this option had to be handled a bit
specially, since it's not declared in nixos/modules like all the other
NixOS options.

Co-Authored-By: pennae <github@quasiparticle.net>
Co-Authored-By: Robert Hensing <robert@roberthensing.nl>

lib/modules.nix

@@ -46,6 +46,7 @@ let
     showFiles
     showOption
     unknownModule
+    literalExpression
     ;
 
   showDeclPrefix = loc: decl: prefix:
@@ -140,7 +141,7 @@ rec {
       # this module is used, to avoid conflicts and allow chaining of
       # extendModules.
       internalModule = rec {
-        _file = ./modules.nix;
+        _file = "lib/modules.nix";
 
         key = _file;
 
@@ -153,8 +154,91 @@ rec {
             # a `_module.args.pkgs = import (fetchTarball { ... }) {}` won't
             # start a download when `pkgs` wasn't evaluated.
             type = types.lazyAttrsOf types.raw;
-            internal = true;
-            description = "Arguments passed to each module.";
+            # Only render documentation once at the root of the option tree,
+            # not for all individual submodules.
+            internal = prefix != [];
+            # TODO: Change the type of this option to a submodule with a
+            # freeformType, so that individual arguments can be documented
+            # separately
+            description = ''
+              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>
+              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
+              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>
+              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>
+            '';
           };
 
           _module.check = mkOption {

lib/tests/misc.nix

@@ -691,7 +691,7 @@ runTests {
 
         locs = filter (o: ! o.internal) (optionAttrSetToDocList options);
       in map (o: o.loc) locs;
-    expected = [ [ "foo" ] [ "foo" "<name>" "bar" ] [ "foo" "bar" ] ];
+    expected = [ [ "_module" "args" ] [ "foo" ] [ "foo" "<name>" "bar" ] [ "foo" "bar" ] ];
   };
 
   testCartesianProductOfEmptySet = {

nixos/lib/make-options-doc/mergeJSON.py

@@ -48,7 +48,9 @@ overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))
 
 # fix up declaration paths in lazy options, since we don't eval them from a full nixpkgs dir
 for (k, v) in options.items():
-    v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}', v.value['declarations']))
+    # The _module options are not declared in nixos/modules
+    if v.value['loc'][0] != "_module":
+        v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}', v.value['declarations']))
 
 # merge both descriptions
 for (k, v) in overrides.items():