most modules can be evaluated for their documentation in a very restricted environment that doesn't include all of nixpkgs. this evaluation can then be cached and reused for subsequent builds, merging only documentation that has changed into the cached set. since nixos ships with a large number of modules of which only a few are used in any given config this can save evaluation a huge percentage of nixos options available in any given config. in tests of this caching, despite having to copy most of nixos/, saves about 80% of the time needed to build the system manual, or about two second on the machine used for testing. build time for a full system config shrank from 9.4s to 7.4s, while turning documentation off entirely shortened the build to 7.1s.
77 lines
2 KiB
Nix
77 lines
2 KiB
Nix
{ lib, ... }:
|
|
|
|
with lib;
|
|
|
|
let
|
|
maintainer = mkOptionType {
|
|
name = "maintainer";
|
|
check = email: elem email (attrValues lib.maintainers);
|
|
merge = loc: defs: listToAttrs (singleton (nameValuePair (last defs).file (last defs).value));
|
|
};
|
|
|
|
listOfMaintainers = types.listOf maintainer // {
|
|
# Returns list of
|
|
# { "module-file" = [
|
|
# "maintainer1 <first@nixos.org>"
|
|
# "maintainer2 <second@nixos.org>" ];
|
|
# }
|
|
merge = loc: defs:
|
|
zipAttrs
|
|
(flatten (imap1 (n: def: imap1 (m: def':
|
|
maintainer.merge (loc ++ ["[${toString n}-${toString m}]"])
|
|
[{ inherit (def) file; value = def'; }]) def.value) defs));
|
|
};
|
|
|
|
docFile = types.path // {
|
|
# Returns tuples of
|
|
# { file = "module location"; value = <path/to/doc.xml>; }
|
|
merge = loc: defs: defs;
|
|
};
|
|
in
|
|
|
|
{
|
|
options = {
|
|
meta = {
|
|
|
|
maintainers = mkOption {
|
|
type = listOfMaintainers;
|
|
internal = true;
|
|
default = [];
|
|
example = literalExpression ''[ lib.maintainers.all ]'';
|
|
description = ''
|
|
List of maintainers of each module. This option should be defined at
|
|
most once per module.
|
|
'';
|
|
};
|
|
|
|
doc = mkOption {
|
|
type = docFile;
|
|
internal = true;
|
|
example = "./meta.chapter.xml";
|
|
description = ''
|
|
Documentation prologue for the set of options of each module. This
|
|
option should be defined at most once per module.
|
|
'';
|
|
};
|
|
|
|
buildDocsInSandbox = mkOption {
|
|
type = types.bool // {
|
|
merge = loc: defs: defs;
|
|
};
|
|
internal = true;
|
|
default = true;
|
|
description = ''
|
|
Whether to include this module in the split options doc build.
|
|
Disable if the module references `config`, `pkgs` or other module
|
|
arguments that cannot be evaluated as constants.
|
|
|
|
This option should be defined at most once per module.
|
|
'';
|
|
};
|
|
|
|
};
|
|
};
|
|
|
|
meta.maintainers = singleton lib.maintainers.pierron;
|
|
}
|