This change makes `baseOptionsJSON` (`lazy-option.json`) take
our existing `documentation.nixos.options.warningsAreErrors` option into
account to then set the `NIX_ABORT_ON_WARN` environment variable within
its build sandbox accordingly.
Given `documentation.nixos.options.warningsAreErrors` default to true,
our nixpkgs CI check that builds the NixOS manual for each PR, will now
fail when something raises a warning, e.g. as part of the `lib.mdDoc`
deprecation.
This should prevent new PRs with lib.mdDoc from getting merged.
Previously, the manual would build successfully, even if an eval warning
was raised.
see #277861. as the module list grows the argument size in the
lazy-options nix call grows, eventually reaching a hard limit and
causing the build to fail. writing the list to a file instead and import
it instead of providing it directly circumvents this.
- Move contents of README.md from
nixos/modules/installer/tools/manpages/ to
nixos/doc/manual/contributing-to-this-manual.chapter.md.
- Don't mention DocBook as its obsolete and too specific.
- Rename derivation attribute name of configuration.nix(5) manual page,
both on the `contributing-to-this-manual.chapter.md`, and in other
places.
Since each such `nixos-*` tool has it's own derivation, exposed in pkgs,
There is no point in separating the manuals from the packages. If
someone wishes to have the tools without the manuals, they can use
meta.outputsToInstall to disable the installation of the manpages of
these packages. This Fixes#244450.
they're no longer necessary for us and will almost definitely start to
rot now (like commonmark and asciidoc outputs did previously). most
existing users seem to take the docbook output and run it through pandoc
to generate html, those can easily migrate to use commonmark instead.
other users will hopefully pipe up when they notice that things they rely
on are going away.
optionsUsedDocbook has only been around for one release and only exposed
to allow other places to generate warnings, so that does not deserve
such precautions.
it's been long in the making, and with 23.05 out we can finally disable
docbook option docs and default to markdown instead. this brings a
massive speed boost in manual and manpage builds, so much so that we may
consider enabling user module documentation by default.
we don't remove the docbook support code entirely yet because it's a lot
all over, and probably better removed in multiple separate changes.
This allows modules that declare their class to be checked.
While that's not most user modules, frameworks can take advantage
of this by setting declaring the module class for their users.
That way, the mistake of importing a module into the wrong hierarchy
can be reported more clearly in some cases.
following the plan in https://github.com/NixOS/nixpkgs/pull/189318#discussion_r961764451
also adds an activation script to print the warning during activation
instead of during build, otherwise folks using the new CLI that hides
build logs by default might never see the warning.
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`.
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.
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.
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.
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.
