Render un`_type`d defaults and examples as `literalExpression`s using
`lib.generators.toPretty` so that consumers don't have to reinvent Nix
pretty-printing. `renderOptionValue` is kept internal for now intentionally.
Make `toPretty` print floats as valid Nix values (without a tilde).
Get rid of the now-obsolete `substSpecial` function.
Move towards disallowing evaluation of packages in the manual by
raising a warning on `pkgs.foo.{outPath,drvPath}`; later, this should
throw an error. Instead, module authors should use `literalExpression`
and `mkPackageOption`.
Currently, we build `man-cache` with `runCommandLocal`, which causes it
to get re-built locally instead of fetched from cache. While the
resulting derivation might be small, it does take a fair bit of time to
build for all my systems, and would be _far_ quicker to fetch.
With this change, we use `runCommand` instead of `runCommandLocal`,
allowing it to get fetched from cache instead of rebuilt for all hosts.
It gives a warning on the lazy-trees branch of Nix
(https://github.com/NixOS/nix/pull/6530) and should generally be
avoided because it causes an unnecessary copy to the store.
deprecate literalDocBook by adding a warning (that will not fire yet) to
its uses and other docbook literal strings by adding optional warning
message to mergeJSON.
most of these are hidden because they're either part of a submodule that
doesn't have its type rendered (eg because the submodule type is used in
an either type) or because they are explicitly hidden. some of them are
merely hidden from nix-doc-munge by how their option is put together.
conversions were done using https://github.com/pennae/nix-doc-munge
using (probably) rev f34e145 running
nix-doc-munge nixos/**/*.nix
nix-doc-munge --import nixos/**/*.nix
the tool ensures that only changes that could affect the generated
manual *but don't* are committed, other changes require manual review
and are discarded.
mostly no rendering changes. some lists (like simplelist) don't have an
exact translation to markdown, so we use a comma-separated list of
literals instead.
most of the screen tags used in option docs are actually listings of
some sort. nsd had a notable exception where its screen usage was pretty
much a raw markdown block that made most sense to convert into docbook lists.
now nix-doc-munge will not introduce whitespace changes when it replaces
manpage references with the MD equivalent.
no change to the manpage, changes to the HTML manual are whitespace only.
markdown can't represent the difference without another extension and
both the html manual and the manpage render them the same, so keeping the
distinction is not very useful on its own. with the distinction removed
we can automatically convert many options that use <code> tags to markdown.
the manpage remains unchanged, html manual does not render
differently (but class names on code tags do change from "code" to "literal").
the conversion procedure is simple:
- find all things that look like options, ie calls to either `mkOption`
or `lib.mkOption` that take an attrset. remember the attrset as the
option
- for all options, find a `description` attribute who's value is not a
call to `mdDoc` or `lib.mdDoc`
- textually convert the entire value of the attribute to MD with a few
simple regexes (the set from mdize-module.sh)
- if the change produced a change in the manual output, discard
- if the change kept the manual unchanged, add some text to the
description to make sure we've actually found an option. if the
manual changes this time, keep the converted description
this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.
The ${opt.*} syntax will print the full path when NixOS is used
as a submodule.
nixpkgs.system / nixpkgs.localSystem must not be read by any
other module because its meaning is ambiguous in cross vs
non-cross contexts. hostPlatform is generally what you need.
*Where* you build something generally doesn't matter in a
system _configuration_ context like NixOS.
Riak have been updated a lot since the version 2.2 (now 3.0.10) but
has seen no updated to the package. This is at this point
a problem forcing us to maintain old versions of erlang.
We would be happy to re accept a newer version of Riak if someone want
to spend the time to set it up.
- initialSystem was keeping track of the evaluating system
- it had been used by `nesting.children`
- since, 20.09, `nesting.children` has been replaced with named
specializations
It appears that this option was left over and not cleand up properly.
It doesn't make sense to have a default value for this that's
incompatible with the default locate implementation. It means that
just doing services.locate.enable = true; generates a warning, even if
you don't care about pruning anything. So only use the default prune
list if the locate implementation supports it (i.e., isn't findutils).
Addresses #16545. Allows for user defined environment variables that
hold paths to wordlists. This is to allow for easy access to wordlists
for users and scripts, (in other distributions a convenient wordlist is
typically found in /usr/share/dict/words or similar). The default
wordlist is the one found in scowl, for no other reason than that's the
one that was mentioned in the linked issue.
It is possible to specify multiple environment variables as well. This
is for users who need multiple wordlists (such as multilingual users).
Still actively developed and yet stuck on python2. Also marked as
vulnerable and their issue tracker contains yet another security issue
reported in 2021/10 that the upstream hasn't acknowledged yet.
Mind blown.
Closes: #135543, #97274, #97275
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.
