Commit Graph

69 Commits

Author SHA1 Message Date
Doron Behar
924a07dc22 nixos/doc: Improve documentation of documentation
- 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.
2023-08-12 22:28:04 +03:00
Doron Behar
32f75a0f2a nixos/install-tools: Add manpages to packages instead of seperating them
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.
2023-08-12 18:01:06 +03:00
pennae
f52f531a4e nixos/make-options-doc: deprecate docbook outputs
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.
2023-06-13 16:56:32 +02:00
pennae
0997ae1903 nixos/manual: disallow docbook option docs
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.
2023-06-13 16:56:30 +02:00
Robert Hensing
8054785157 lib/modules: Move class out of specialArgs 2023-05-06 18:32:58 +02:00
Robert Hensing
79703eef08 nixos,nixpkgs: Add module classes
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.
2023-05-06 18:29:04 +02:00
simeplejack-src
fe28e8f1e6 nixos/documentation: Fix desktopIcon, GenericName/Comment 2023-03-29 22:23:39 -04:00
pennae
df09c21fb2 nixos/documentation: deprecate docbook option docs
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.
2023-01-22 17:08:40 +01:00
pennae
9da5f12ecf modules: add mkPackageOptionMD
another transitional option factory, like mkAliasOptionModuleMD.
2023-01-05 02:33:13 +01:00
K900
2d3cf010fe
Revert "treewide: use nativeBuildInputs with runCommand instead of inlining" 2022-12-26 21:05:35 +03:00
Sandro Jäckel
26f704b545
treewide: use nativeBuildInputs with runCommand instead of inlining 2022-12-18 23:36:40 +01:00
Naïm Favier
6a117e2759 nixos/doc: render option values using lib.generators.toPretty
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`.
2022-12-08 17:52:52 +01:00
Eelco Dolstra
2e860868fe nixos/modules/misc/documentation.nix: Don't use toString on a path
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.
2022-10-28 17:05:03 +02:00
pennae
767485a0de lib/options: deprecate docbook text and literalDocBook
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.
2022-09-10 18:23:13 +02:00
pennae
c915b915b5 nixos/*: md-convert options with unordered lists
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.
2022-08-31 16:32:53 +02:00
pennae
6039648c50 nixos/*: automatically convert option docs 2022-08-19 22:40:58 +02:00
pennae
50f9b3107a
Merge pull request #185474 from pennae/option-docs-md
nixos/*: more options md conversion
2022-08-12 23:23:26 +02:00
pennae
087472b1e5 nixos/*: automatically convert option docs 2022-08-06 20:39:12 +02:00
pennae
423545fe48 nixos/*: normalize manpage references to single-line form
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.
2022-08-05 18:34:50 +02:00
Robert Hensing
08e6f45747 nixos: Declare module dependencies
Working towards a unit-testable documentation module.
2022-07-21 15:32:10 +02:00
Robert Hensing
5a98c63077 nixos: Move getty helpLine definition to getty module
Working towards a unit-testable documentation module.
2022-07-21 15:32:00 +02:00
Robert Hensing
9a0b26b216 nixos/documentation: Make extraModules configurable 2022-07-21 15:31:35 +02:00
Robert Hensing
e135c417bb nixos/documentation: Forward the specialArgs
This is necessary when generating the complete documenation for
configurations that import modules from the module arguments.
2022-07-21 15:31:35 +02:00
pennae
320aa2a791 treewide: attempt at markdown option docs 2022-06-12 12:44:38 +02:00
Alyssa Ross
aeed45992b
nixos/documentation: apply cleanSourceFilter
This will prevent result symlinks, etc. from causing rebuilds of the
manual.
2022-04-08 12:20:28 +00:00
K900
cb2cfba6f7 treewide: switch all desktop file generators to new API
Notably:
- remove explicit arguments that match the defaults
- convert everything to the right Nix types
2022-02-25 13:40:38 -08:00
Robert Hensing
aa877346f8 Revert "nixos/documentation: avoid copying nixpkgs subpaths, iteration 2"
This reverts commit 15a00be189.
2022-01-27 12:35:16 +01:00
Robert Hensing
647b304306 Revert "nixos/documentation.nix: Only use store non-flake pkgs.path directly when already copied"
This reverts commit fecf325059.
2022-01-27 12:35:16 +01:00
Robert Hensing
a732a8de1c Revert "nixos/documentation.nix: Use builtins.storePath when appropriate"
This reverts commit 5d29853c38.
2022-01-27 12:33:10 +01:00
Robert Hensing
5d29853c38 nixos/documentation.nix: Use builtins.storePath when appropriate 2022-01-22 16:47:02 +01:00
Robert Hensing
fecf325059 nixos/documentation.nix: Only use store non-flake pkgs.path directly when already copied 2022-01-22 16:42:08 +01:00
Robert Hensing
15a00be189 nixos/documentation: avoid copying nixpkgs subpaths, iteration 2
This kind of reverts commit 893ffee286.
2022-01-22 16:42:08 +01:00
pennae
9d3ba92d63 nixos/documentation: fix docs cross build
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.
2022-01-08 16:03:23 +01:00
kraem
893ffee286
Revert "nixos/documentation: avoid copying nixpkgs subpaths"
builtins.storePath is not allowed in pure evaluation mode

This reverts commit 1511e72b75.
2022-01-05 12:36:54 +01:00
Robert Hensing
70d27303da
Merge pull request #149532 from pennae/split-docs-build
nixos/*: split docs build
2022-01-04 22:33:23 +01:00
pennae
1511e72b75 nixos/documentation: avoid copying nixpkgs subpaths
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
2022-01-02 19:46:13 +01:00
pennae
50954ad1c5 nixos/make-options-doc: treat missing descriptions as errors by default
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.
2022-01-02 19:46:13 +01:00
pennae
fc614c37c6 nixos/documentation: split options doc build
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.
2022-01-02 19:46:13 +01:00
sternenseemann
f4f7238860 nixos/mandoc: init
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/
2021-12-31 11:17:34 +01:00
sternenseemann
bcc4c34640 nixos/documentation: properly reference apropos(1), mention man -k
man -k is useful to mention as it is -- in constrast to apropos(1) --
actually required by POSIX.
2021-12-31 11:17:34 +01:00
sternenseemann
6a3d020b90 nixos/documentation: move man-db-specifics into new man-db module
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.
2021-12-31 11:17:34 +01:00
Robert Hensing
1a223857ab nixos/documentation: Use new extendModules instead of legacy args 2021-12-02 18:23:43 +00:00
sternenseemann
55c7dfade0 nixos/documentation: index devman by default if enabled
It's quite ridiculous that we currently require manual intervention just
to have devman indexed if dev.enable == true.
2021-11-22 23:39:42 +01:00
Naïm Favier
2ddc335e6f
nixos/doc: clean up defaults and examples 2021-10-04 12:47:20 +02:00
rnhmjoj
e4e5d4d899
nixos/documentation: always show qemu-vm options 2021-09-18 16:58:16 +02:00
Sandro
4f78c74b57
nixos/documentation: use full option names 2021-09-15 22:43:44 +02:00
Naïm Favier
459957f9d4
nixos/documentation: expose manualPages
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.
2021-09-07 11:13:32 +02:00
davidak
aa8373ab1b nixos-icons: fix icons not installed when documentation disabled 2021-07-24 06:50:01 +02:00
Jan Tojnar
53830ca04c
doc: Port stdenv/multiple-output to Markdown 2021-03-14 02:18:40 +01:00
Alyssa Ross
6c3d21aff9
nixos/getty: rename from services.mingetty
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.
2021-01-05 09:09:42 +00:00