a few things should've used buildPackages/nativeBuildInputs to not not require
the host architecture for building docs. tested by building aarch64-linux docs
on x86_64-linux, and the result looks good.
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.
Allows advanced users to select what packages they want to generate the
man cache for, and even more advanced users to make manualPages
content-addressed to avoid needless rebuilds.
It's been 8.5 years since NixOS used mingetty, but the option was
never renamed (despite the file definining the module being renamed in
9f5051b76c ("Rename mingetty module to agetty")).
I've chosen to rename it to services.getty here, rather than
services.agetty, because getty is implemantation-neutral and also the
name of the unit that is generated.
This is to ensure that whenever we install the desktop item we also have
the script installed. Prior to b02719a we always had the reference to
the script in the desktop item. Since desktop items are being copied to
home directories and thus "bit rod" over time that absolute path was
removed.
Previously the NixOS-specific configuration for man-db was in the
package itself and /etc/man.conf was completely ignored.
This change moves it to /etc/man_db.conf, making declarative
configuration practical again.
It's now possible to generate the mandb caches for all packages
installed through NixOS `environment.systemPackages` at build-time.
The standard location for the stateful cache (/var/cache/man) is also
configured to allow users to run `mandb` manually if they wish.
Since generating the cache can be expensive the option is off by
default.
Running the manual on a TTY is useless in the graphical ISOs and not
particularly useful in non-graphical ISOs (since you can also run
'nixos-help').
Fixes#83157.
A centralized list for these renames is not good because:
- It breaks disabledModules for modules that have a rename defined
- Adding/removing renames for a module means having to find them in the
central file
- Merge conflicts due to multiple people editing the central file
It is referenced in various places, but does not work out of the box:
$ nixos-help
/run/current-system/sw/bin/nixos-help: unable to start a web browser; please set $BROWSER
In the user-hidden fallbacks to xdg-open(1) and w3m(1), `nixos-help`
expects tools to be deliberately installed by users.
For default installations and new users in general, this is unlikely to
be the case. Conversely, chances to use `nixos-help` are even higher
in such cases.
Use w3m-nographics by default to ensure documentation is always
available. The documentation browser on ttyS8 already does so, but is
not accessible in every installation, e.g. VMs with only ttyS0 and SSH
available.
This obsoletes including it in the base profile's systemPackages,
so remove the @TODO as done.
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 installs the kio "man:" protocol handler, which fixes the UNIX manual
section in the KDE Help Center.
Note that kde currently parses "/etc/man.conf" manually, if `$MANPATH` is not
set, to build its man page index. (if https://bugs.kde.org/show_bug.cgi?id=404022
is addressed, the "/etc/man.conf" symlink should not be necessary anymore)
lib.optional returns a singleton or an empty list. Therefore the
argument does not need to be wrapped in a list.
An alternative patch could have used lib.optionals but seems like no
more elements are going to be added to the optional list.
I know that "devinfo" output does not currently exist, but so does "devman".
It is mentioned in the nixpkgs manual, but no derivation in nixpkgs actually uses it.
