Include the moved-out modular service infrastructure into the set of
files to evaluate during the docs build.
This was previously unnecessary because even the portable parts were
stored inside the nixos tree.
Enables faster and fully asynchronous generation of the cache at runtime
by maintaining a separate copy of `cfg.manualPages` with appropriate
timestamps so that mandb can pick up relevant changes without having to
re-generate the full cache on nearly every system rebuild.
Format all Nix files using the officially approved formatter,
making the CI check introduced in the previous commit succeed:
nix-build ci -A fmt.check
This is the next step of the of the [implementation](https://github.com/NixOS/nixfmt/issues/153)
of the accepted [RFC 166](https://github.com/NixOS/rfcs/pull/166).
This commit will lead to merge conflicts for a number of PRs,
up to an estimated ~1100 (~33%) among the PRs with activity in the past 2
months, but that should be lower than what it would be without the previous
[partial treewide format](https://github.com/NixOS/nixpkgs/pull/322537).
Merge conflicts caused by this commit can now automatically be resolved while rebasing using the
[auto-rebase script](8616af08d9/maintainers/scripts/auto-rebase).
If you run into any problems regarding any of this, please reach out to the
[formatting team](https://nixos.org/community/teams/formatting/) by
pinging @NixOS/nix-formatting.
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.
While Devhelp now supports finding API documentation in `/share/doc` and the new `gi-docgen` toolchain places it there, older projects using gtk-doc (e.g. GLib) still install it to `/share/gtk-doc` and/or `/share/devhelp/books`.
For people using the major DEs this is not problem since they have `/share` in `pathsToLink` but we want to be explicit and make it work for everyone.
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.
