JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nixos: doc: optionally include all modules in manual generation

Browse Source 
Before this change `man 5 configuration.nix` would only show options of modules in
the `baseModules` set, which consists only of the list of modules in
`nixos/modules/module-list.nix`

With this change applied and `documentation.nixos.includeAllModules` option enabled
all modules included in `configuration.nix` file will be used instead.

This makes configurations with custom modules self-documenting. It also means
that importing non-`baseModules` modules like `gce.nix` or `azure.nix`
will make their documentation available in `man 5 configuration.nix`.

`documentation.nixos.includeAllModules` is currently set to `false` by
default as enabling it usually uncovers bugs and prevents evaluation.
It should be set to `true` in a release or two.

This was originally implemented in #47177, edited for more configurability,
documented and rebased onto master by @oxij.
This commit is contained in:
Arian van Putten 2018-09-23 21:34:36 +02:00 committed by Jan Malakhovski
parent 9b3e5a3aab
commit 2e75a7b516
3 changed files with 28 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
nixos/doc/manual/release-notes/rl-1909.xml
View File

@ -51,7 +51,17 @@
<itemizedlist>
<listitem>
<para />
<para>
The <option>documentation</option> module gained an option named
<option>documentation.nixos.includeAllModules</option> which makes the generated
<citerefentry><refentrytitle>configuration.nix</refentrytitle>
<manvolnum>5</manvolnum></citerefentry> manual page include all options from all NixOS modules
included in a given <literal>configuration.nix</literal> configuration file. Currently, it is
set to <literal>false</literal> by default as enabling it frequently prevents evaluation. But
the plan is to eventually have it set to <literal>true</literal> by default. Please set it to
<literal>true</literal> now in your <literal>configuration.nix</literal> and fix all the bugs
it uncovers.
</para>
</listitem>
</itemizedlist>
</section>

4
nixos/lib/eval-config.nix
View File

@ -51,7 +51,7 @@ in rec {
# system configuration.
inherit (lib.evalModules {
inherit prefix check;
modules = modules ++ extraModules ++ baseModules ++ [ pkgsModule ];
modules = baseModules ++ extraModules ++ [ pkgsModule ] ++ modules;
args = extraArgs;
specialArgs =
{ modulesPath = builtins.toString ../modules; } // specialArgs;
@ -60,7 +60,7 @@ in rec {
# These are the extra arguments passed to every module. In
# particular, Nixpkgs is passed through the "pkgs" argument.
extraArgs = extraArgs_ // {
inherit modules baseModules;
inherit baseModules extraModules modules;
};
inherit (config._module.args) pkgs;

17
nixos/modules/misc/documentation.nix
View File

@ -1,4 +1,4 @@
{ config, lib, pkgs, baseModules, ... }:
{ config, lib, pkgs, baseModules, extraModules, modules, ... }:
with lib;
@ -6,6 +6,8 @@ let
cfg = config.documentation;
manualModules = baseModules ++ optionals cfg.nixos.includeAllModules (extraModules ++ modules);
/* For the purpose of generating docs, evaluate options with each derivation
in `pkgs` (recursively) replaced by a fake with path "\${pkgs.attribute.path}".
It isn't perfect, but it seems to cover a vast majority of use cases.
@ -18,7 +20,7 @@ let
options =
let
scrubbedEval = evalModules {
modules = [ { nixpkgs.localSystem = config.nixpkgs.localSystem; } ] ++ baseModules;
modules = [ { nixpkgs.localSystem = config.nixpkgs.localSystem; } ] ++ manualModules;
args = (config._module.args) // { modules = [ ]; };
specialArgs = { pkgs = scrubDerivations "pkgs" pkgs; };
};
@ -146,6 +148,17 @@ in
'';
};
nixos.includeAllModules = mkOption {
type = types.bool;
default = false;
description = ''
Whether the generated NixOS's documentation should include documentation for all
the options from all the NixOS modules included in the current
<literal>configuration.nix</literal>. Disabling this will make the manual
generator to ignore options defined outside of <literal>baseModules</literal>.
'';
};
};
};