From 2e75a7b516581bedcf236a0f21730185a9d1f11b Mon Sep 17 00:00:00 2001 From: Arian van Putten Date: Sun, 23 Sep 2018 21:34:36 +0200 Subject: [PATCH 1/3] nixos: doc: optionally include all modules in manual generation 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. --- nixos/doc/manual/release-notes/rl-1909.xml | 12 +++++++++++- nixos/lib/eval-config.nix | 4 ++-- nixos/modules/misc/documentation.nix | 17 +++++++++++++++-- 3 files changed, 28 insertions(+), 5 deletions(-) diff --git a/nixos/doc/manual/release-notes/rl-1909.xml b/nixos/doc/manual/release-notes/rl-1909.xml index baf08d70bfb..f54592b6bf6 100644 --- a/nixos/doc/manual/release-notes/rl-1909.xml +++ b/nixos/doc/manual/release-notes/rl-1909.xml @@ -51,7 +51,17 @@ - + + The module gained an option named + which makes the generated + configuration.nix + 5 manual page include all options from all NixOS modules + included in a given configuration.nix configuration file. Currently, it is + set to false by default as enabling it frequently prevents evaluation. But + the plan is to eventually have it set to true by default. Please set it to + true now in your configuration.nix and fix all the bugs + it uncovers. + diff --git a/nixos/lib/eval-config.nix b/nixos/lib/eval-config.nix index 5f05b037bdd..77490ca3762 100644 --- a/nixos/lib/eval-config.nix +++ b/nixos/lib/eval-config.nix @@ -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; diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index 9b2e1235b74..834ac0de912 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -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 + configuration.nix. Disabling this will make the manual + generator to ignore options defined outside of baseModules. + ''; + }; + }; }; From ca496b194f7c16e252a8cd0f7e3942823defc5a0 Mon Sep 17 00:00:00 2001 From: Jan Malakhovski Date: Tue, 27 Mar 2018 17:58:44 +0000 Subject: [PATCH 2/3] nixos: doc: increase maxdepth for xsltproc See https://github.com/NixOS/nixpkgs/issues/37903#issuecomment-376618117 for details. With the previous patch and some custom modules included in `configuration.nix` the above bug is very easy to trigger. This is a simplest workaround I have. A proper solution would look like https://github.com/NixOS/nixpkgs/issues/37903#issuecomment-376980838. --- nixos/doc/manual/default.nix | 1 + 1 file changed, 1 insertion(+) diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 02b91773f5d..4e0d486e94c 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -327,6 +327,7 @@ in rec { # Generate manpages. mkdir -p $out/share/man xsltproc --nonet \ + --maxdepth 6000 \ --param man.output.in.separate.dir 1 \ --param man.output.base.dir "'$out/share/man/'" \ --param man.endnotes.are.numbered 0 \ From a53b3ba091153de98b76e42d4a90607179bf64bf Mon Sep 17 00:00:00 2001 From: Jan Malakhovski Date: Fri, 22 Feb 2019 00:05:58 +0000 Subject: [PATCH 3/3] lib: optionAttrSetToDocList: warn instead of throwing on options without descriptions For convenience, it's not like not having a description is deadly or something. --- lib/options.nix | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/options.nix b/lib/options.nix index 5cea99067aa..d46dec6e41c 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -141,7 +141,7 @@ rec { docOption = rec { loc = opt.loc; name = showOption opt.loc; - description = opt.description or (throw "Option `${name}' has no description."); + description = opt.description or (lib.warn "Option `${name}' has no description." "This option has no description."); declarations = filter (x: x != unknownModule) opt.declarations; internal = opt.internal or false; visible = opt.visible or true;