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.
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.
some options have default that are best described in prose, such as
defaults that depend on the system stateVersion, defaults that are
derivations specific to the surrounding context, or those where the
expression is much longer and harder to understand than a simple text
snippet.
Dash `echo` interprets backslash escapes. This causes two consecutive backslashes in JSON to turn into a single one before the string is passed to jq, resulting in a parsing error.
This is useful for situations in which you might want to reset certain
things using `--reset-database` or `--reset-deltas` or debug certain
things using any of the debug options like `--debug-perf-stats`.
Signed-off-by: Jakub Sokołowski <jakub@status.im>
Many options define their example to be a Nix value without using
literalExample. This sometimes gets rendered incorrectly in the manual,
causing confusion like in https://github.com/NixOS/nixpkgs/issues/25516
This fixes it by using literalExample for such options. The list of
option to fix was determined with this expression:
let
nixos = import ./nixos { configuration = {}; };
lib = import ./lib;
valid = d: {
# escapeNixIdentifier from https://github.com/NixOS/nixpkgs/pull/82461
set = lib.all (n: lib.strings.escapeNixIdentifier n == n) (lib.attrNames d) && lib.all (v: valid v) (lib.attrValues d);
list = lib.all (v: valid v) d;
}.${builtins.typeOf d} or true;
optionList = lib.optionAttrSetToDocList nixos.options;
in map (opt: {
file = lib.elemAt opt.declarations 0;
loc = lib.options.showOption opt.loc;
}) (lib.filter (opt: if opt ? example then ! valid opt.example else false) optionList)
which when evaluated will output all options that use a Nix identifier
that would need escaping as an attribute name.
The following configuration generates a systemd unit that doesn't
start.
```nix
{
services.syncthing = {
enable = true;
user = "my-user";
};
}
```
It fails with
```
systemd[1]: Started Syncthing service.
systemd[6745]: syncthing.service: Failed to determine group credentials: No such process
systemd[6745]: syncthing.service: Failed at step GROUP spawning /nix/store/n1ydz3i08nqp1ajc50ycy1zribmphqc9-syncthing-1.1.4-bin/bin/syncthing: No such process
systemd[1]: syncthing.service: Main process exited, code=exited, status=216/GROUP
systemd[1]: syncthing.service: Failed with result 'exit-code'.
```
This is due to the fact that `syncthing` group (default) is not
created if the user is overridden.
Add a separate check for setting up the default group, so that
user/group are created independently.
We were already creating a group for the user under which to run syncthing but
we were defaulting to running as `nogroup`.
Additionally, use `install` instead of multiple calls to mkdir/cp/chown.
Currently only for the user services as NixOS handles the named system
instances slightly differently.
syncthing and syncthing-inotify are done the same way.
There are 4 parts to this:
1) Copy in the upstream unit files
2) Make the nixos module use the definition from upstream
3) Enable restarting of all instances (system and user) on resume
4) Allow the traffic in the firewall on default ports if wanted
fixes#18973
- add missing types in module definitions
- add missing 'defaultText' in module definitions
- wrap example with 'literalExample' where necessary in module definitions
