diff options
author | Robert Hensing <roberth@users.noreply.github.com> | 2022-01-04 22:33:23 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-01-04 22:33:23 +0100 |
commit | 70d27303da48e20dd60636c9c16890aaeedaf275 (patch) | |
tree | 4d07091bff7fc5a71a0a7b818b8b29e4535caa8d /nixos/doc | |
parent | d8e579906315e8648031b9b4e9a25bb7e4f404fe (diff) | |
parent | 1511e72b75b49cdeeee68def0c203f997d01bafa (diff) | |
download | nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.tar nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.tar.gz nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.tar.bz2 nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.tar.lz nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.tar.xz nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.tar.zst nixpkgs-70d27303da48e20dd60636c9c16890aaeedaf275.zip |
Merge pull request #149532 from pennae/split-docs-build
nixos/*: split docs build
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/default.nix | 17 | ||||
-rw-r--r-- | nixos/doc/manual/development/meta-attributes.section.md | 28 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/development/meta-attributes.section.xml | 44 |
3 files changed, 82 insertions, 7 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 31b6da01c6b..52d500c64d3 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -1,4 +1,13 @@ -{ pkgs, options, config, version, revision, extraSources ? [] }: +{ pkgs +, options +, config +, version +, revision +, extraSources ? [] +, baseOptionsJSON ? null +, warningsAreErrors ? true +, prefix ? ../../.. +}: with pkgs; @@ -11,11 +20,11 @@ let # # E.g. if some `options` came from modules in ${pkgs.customModules}/nix, # you'd need to include `extraSources = [ pkgs.customModules ]` - prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); + prefixesToStrip = map (p: "${toString p}/") ([ prefix ] ++ extraSources); stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip; optionsDoc = buildPackages.nixosOptionsDoc { - inherit options revision; + inherit options revision baseOptionsJSON warningsAreErrors; transformOptions = opt: opt // { # Clean up declaration sites to not refer to the NixOS source tree. declarations = map stripAnyPrefixes opt.declarations; @@ -161,7 +170,7 @@ let in rec { inherit generatedSources; - inherit (optionsDoc) optionsJSON optionsDocBook; + inherit (optionsDoc) optionsJSON optionsNix optionsDocBook; # Generate the NixOS manual. manualHTML = runCommand "nixos-manual-html" diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md index ca4ba007f7d..946c08efd0a 100644 --- a/nixos/doc/manual/development/meta-attributes.section.md +++ b/nixos/doc/manual/development/meta-attributes.section.md @@ -5,7 +5,7 @@ extra information. Module meta attributes are defined in the `meta.nix` special module. `meta` is a top level attribute like `options` and `config`. Available -meta-attributes are `maintainers` and `doc`. +meta-attributes are `maintainers`, `doc`, and `buildDocsInSandbox`. Each of the meta-attributes must be defined at most once per module file. @@ -24,6 +24,7 @@ file. meta = { maintainers = with lib.maintainers; [ ericsagnes ]; doc = ./default.xml; + buildDocsInSandbox = true; }; } ``` @@ -38,3 +39,28 @@ file. ```ShellSession $ nix-build nixos/release.nix -A manual.x86_64-linux ``` + +- `buildDocsInSandbox` indicates whether the option documentation for the + module can be built in a derivation sandbox. This option is currently only + honored for modules shipped by nixpkgs. User modules and modules taken from + `NIXOS_EXTRA_MODULE_PATH` are always built outside of the sandbox, as has + been the case in previous releases. + + Building NixOS option documentation in a sandbox allows caching of the built + documentation, which greatly decreases the amount of time needed to evaluate + a system configuration that has NixOS documentation enabled. The sandbox also + restricts which attributes may be referenced by documentation attributes + (such as option descriptions) to the `options` and `lib` module arguments and + the `pkgs.formats` attribute of the `pkgs` argument, `config` and the rest of + `pkgs` are disallowed and will cause doc build failures when used. This + restriction is necessary because we cannot reproduce the full nixpkgs + instantiation with configuration and overlays from a system configuration + inside the sandbox. The `options` argument only includes options of modules + that are also built inside the sandbox, referencing an option of a module + that isn't built in the sandbox is also forbidden. + + The default is `true` and should usually not be changed; set it to `false` + only if the module requires access to `pkgs` in its documentation (e.g. + because it loads information from a linked package to build an option type) + or if its documentation depends on other modules that also aren't sandboxed + (e.g. by using types defined in the other module). diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml index f535d94602b..1eb6e0f3036 100644 --- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml +++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml @@ -8,8 +8,8 @@ <para> <literal>meta</literal> is a top level attribute like <literal>options</literal> and <literal>config</literal>. Available - meta-attributes are <literal>maintainers</literal> and - <literal>doc</literal>. + meta-attributes are <literal>maintainers</literal>, + <literal>doc</literal>, and <literal>buildDocsInSandbox</literal>. </para> <para> Each of the meta-attributes must be defined at most once per module @@ -29,6 +29,7 @@ meta = { maintainers = with lib.maintainers; [ ericsagnes ]; doc = ./default.xml; + buildDocsInSandbox = true; }; } </programlisting> @@ -51,5 +52,44 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux </programlisting> </listitem> + <listitem> + <para> + <literal>buildDocsInSandbox</literal> indicates whether the + option documentation for the module can be built in a derivation + sandbox. This option is currently only honored for modules + shipped by nixpkgs. User modules and modules taken from + <literal>NIXOS_EXTRA_MODULE_PATH</literal> are always built + outside of the sandbox, as has been the case in previous + releases. + </para> + <para> + Building NixOS option documentation in a sandbox allows caching + of the built documentation, which greatly decreases the amount + of time needed to evaluate a system configuration that has NixOS + documentation enabled. The sandbox also restricts which + attributes may be referenced by documentation attributes (such + as option descriptions) to the <literal>options</literal> and + <literal>lib</literal> module arguments and the + <literal>pkgs.formats</literal> attribute of the + <literal>pkgs</literal> argument, <literal>config</literal> and + the rest of <literal>pkgs</literal> are disallowed and will + cause doc build failures when used. This restriction is + necessary because we cannot reproduce the full nixpkgs + instantiation with configuration and overlays from a system + configuration inside the sandbox. The <literal>options</literal> + argument only includes options of modules that are also built + inside the sandbox, referencing an option of a module that isn’t + built in the sandbox is also forbidden. + </para> + <para> + The default is <literal>true</literal> and should usually not be + changed; set it to <literal>false</literal> only if the module + requires access to <literal>pkgs</literal> in its documentation + (e.g. because it loads information from a linked package to + build an option type) or if its documentation depends on other + modules that also aren’t sandboxed (e.g. by using types defined + in the other module). + </para> + </listitem> </itemizedlist> </section> |