the docs build should work well even when called from a git checkout of
nixpkgs, but should avoid as much work as possible in all cases.
if pkgs.path is already a store path we can avoid copying parts of it
into the docs build sandbox by wrapping pkgs.path in builtins.storePath
this partially solves the problem of "missing description" warnings of the
options doc build being lost by nix build, at the cost of failing builds that
previously ran. an option to disable this behaviour is provided.
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.
Adds a NixOS module which allows using mandoc as the main manual
viewer. It can be used as a drop-in replacement for documentation.man
which relies on GNU's man-db and provides more or less the same
features.
The generateCaches option requires a different implementation for
mandoc, so it is hard to share code between the two modules -- hence it
has been implemented separately. Using both at the same time makes
little sense and wouldn't quite work, so there's an assertion to
prevent it.
To make makewhatis(8) index manual pages which are symlinks to the nix
store, we need to set READ_ALLOWED_PATH to include
`builtins.storeDir`. For background and discussion see:
https://inbox.vuxu.org/mandoc-tech/c9932669-e9d4-1454-8708-7c8e36967e8e@systemli.org/T/
It may be possible to revert the move of `documentation.man.manualPages`
later. The problem is that other man implementations (mandoc) want to
generate their index databases in place, so the approach taken here
doesn't translate super well.
PRUNE_BIND_MOUNTSFR seems to be a typo.
The man page only mentions it in a header and further in the paragraph
it is PRUNE_BIND_MOUNTS.
Also breaks plocate which complains about the unknown option.
