nixos/treewide: Fix incorrectly rendered examples

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.

Changed files
+92 -59
nixos
modules
services
virtualisation
+5 -3
nixos/modules/services/amqp/activemq/default.nix
···
javaProperties = mkOption {
type = types.attrs;
default = { };
-
example = {
-
"java.net.preferIPv4Stack" = "true";
-
};
+
example = literalExample ''
+
{
+
"java.net.preferIPv4Stack" = "true";
+
}
+
'';
apply = attrs: {
"activemq.base" = "${cfg.baseDir}";
"activemq.data" = "${cfg.baseDir}/data";
+5 -1
nixos/modules/services/backup/syncoid.nix
···
};
}));
default = {};
-
example."pool/test".target = "root@target:pool/test";
+
example = literalExample ''
+
{
+
"pool/test".target = "root@target:pool/test";
+
}
+
'';
description = "Syncoid commands to run.";
};
};
+20 -12
nixos/modules/services/cluster/hadoop/default.nix
···
options.services.hadoop = {
coreSite = mkOption {
default = {};
-
example = {
-
"fs.defaultFS" = "hdfs://localhost";
-
};
+
example = literalExample ''
+
{
+
"fs.defaultFS" = "hdfs://localhost";
+
}
+
'';
description = "Hadoop core-site.xml definition";
};
hdfsSite = mkOption {
default = {};
-
example = {
-
"dfs.nameservices" = "namenode1";
-
};
+
example = literalExample ''
+
{
+
"dfs.nameservices" = "namenode1";
+
}
+
'';
description = "Hadoop hdfs-site.xml definition";
};
mapredSite = mkOption {
default = {};
-
example = {
-
"mapreduce.map.cpu.vcores" = "1";
-
};
+
example = literalExample ''
+
{
+
"mapreduce.map.cpu.vcores" = "1";
+
}
+
'';
description = "Hadoop mapred-site.xml definition";
};
yarnSite = mkOption {
default = {};
-
example = {
-
"yarn.resourcemanager.ha.id" = "resourcemanager1";
-
};
+
example = literalExample ''
+
{
+
"yarn.resourcemanager.ha.id" = "resourcemanager1";
+
}
+
'';
description = "Hadoop yarn-site.xml definition";
};
+3 -2
nixos/modules/services/network-filesystems/netatalk.nix
···
Set of AFP volumes to export.
See <literal>man apf.conf</literal> for more information.
'';
-
example =
+
example = literalExample ''
{ srv =
{ path = "/srv";
"read only" = true;
"hosts allow" = "10.1.0.0/16 10.2.1.100 2001:0db8:1234::/48";
};
-
};
+
}
+
'';
};
extmap = mkOption {
+3 -2
nixos/modules/services/network-filesystems/rsyncd.nix
···
See <command>man rsyncd.conf</command> for options.
'';
type = types.attrsOf (types.attrsOf types.str);
-
example =
+
example = literalExample ''
{ srv =
{ path = "/srv";
"read only" = "yes";
comment = "Public rsync share.";
};
-
};
+
}
+
'';
};
user = mkOption {
+3 -2
nixos/modules/services/network-filesystems/samba.nix
···
See <command>man smb.conf</command> for options.
'';
type = types.attrsOf (types.attrsOf types.unspecified);
-
example =
+
example = literalExample ''
{ public =
{ path = "/srv/public";
"read only" = true;
···
"guest ok" = "yes";
comment = "Public samba share.";
};
-
};
+
}
+
'';
};
};
+6 -4
nixos/modules/services/networking/3proxy.nix
···
nsrecord = mkOption {
type = types.attrsOf types.str;
default = { };
-
example = {
-
"files.local" = "192.168.1.12";
-
"site.local" = "192.168.1.43";
-
};
+
example = literalExample ''
+
{
+
"files.local" = "192.168.1.12";
+
"site.local" = "192.168.1.43";
+
}
+
'';
description = "Adds static nsrecords.";
};
};
+6 -4
nixos/modules/services/networking/dnscache.nix
···
Table of {hostname: server} pairs to use as authoritative servers for hosts (and subhosts).
If entry for @ is not specified predefined list of root servers is used.
'';
-
example = {
-
"@" = ["8.8.8.8" "8.8.4.4"];
-
"example.com" = ["192.168.100.100"];
-
};
+
example = literalExample ''
+
{
+
"@" = ["8.8.8.8" "8.8.4.4"];
+
"example.com" = ["192.168.100.100"];
+
}
+
'';
};
forwardOnly = mkOption {
+7 -3
nixos/modules/services/networking/ndppd.nix
···
timeout = mkOption {
type = types.int;
description = ''
-
Controls how long to wait for a Neighbor Advertisment Message before
+
Controls how long to wait for a Neighbor Advertisment Message before
invalidating the entry, in milliseconds.
'';
default = 500;
···
ttl = mkOption {
type = types.int;
description = ''
-
Controls how long a valid or invalid entry remains in the cache, in
+
Controls how long a valid or invalid entry remains in the cache, in
milliseconds.
'';
default = 30000;
···
messages, and respond to them according to a set of rules.
'';
default = {};
-
example = { eth0.rules."1111::/64" = {}; };
+
example = literalExample ''
+
{
+
eth0.rules."1111::/64" = {};
+
}
+
'';
};
};
+16 -14
nixos/modules/services/networking/strongswan.nix
···
inherit (builtins) toFile;
inherit (lib) concatMapStringsSep concatStringsSep mapAttrsToList
-
mkIf mkEnableOption mkOption types;
+
mkIf mkEnableOption mkOption types literalExample;
cfg = config.services.strongswan;
···
connections = mkOption {
type = types.attrsOf (types.attrsOf types.str);
default = {};
-
example = {
-
"%default" = {
-
keyexchange = "ikev2";
-
keyingtries = "1";
-
};
-
roadwarrior = {
-
auto = "add";
-
leftcert = "/run/keys/moonCert.pem";
-
leftid = "@moon.strongswan.org";
-
leftsubnet = "10.1.0.0/16";
-
right = "%any";
-
};
-
};
+
example = literalExample ''
+
{
+
"%default" = {
+
keyexchange = "ikev2";
+
keyingtries = "1";
+
};
+
roadwarrior = {
+
auto = "add";
+
leftcert = "/run/keys/moonCert.pem";
+
leftid = "@moon.strongswan.org";
+
leftsubnet = "10.1.0.0/16";
+
right = "%any";
+
};
+
}
+
'';
description = ''
A set of connections and their options for the ‘conn xxx’
sections of the <filename>ipsec.conf</filename> file.
+8 -6
nixos/modules/services/networking/syncthing.nix
···
description = ''
folders which should be shared by syncthing.
'';
-
example = {
-
"/home/user/sync" = {
-
id = "syncme";
-
devices = [ "bigbox" ];
-
};
-
};
+
example = literalExample ''
+
{
+
"/home/user/sync" = {
+
id = "syncme";
+
devices = [ "bigbox" ];
+
};
+
}
+
'';
type = types.attrsOf (types.submodule ({ name, ... }: {
options = {
+5 -3
nixos/modules/services/web-apps/youtrack.nix
···
https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Java-Start-Parameters.html
for more information.
'';
-
example = {
-
"jetbrains.youtrack.overrideRootPassword" = "tortuga";
-
};
+
example = literalExample ''
+
{
+
"jetbrains.youtrack.overrideRootPassword" = "tortuga";
+
}
+
'';
type = types.attrsOf types.str;
};
+5 -3
nixos/modules/virtualisation/containers.nix
···
bindMounts = mkOption {
type = with types; loaOf (submodule bindMountOpts);
default = {};
-
example = { "/home" = { hostPath = "/home/alice";
-
isReadOnly = false; };
-
};
+
example = literalExample ''
+
{ "/home" = { hostPath = "/home/alice";
+
isReadOnly = false; };
+
}
+
'';
description =
''