From 1d0fc9729dd8564dc75b5fd020da6bd61e0346c0 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 2 Apr 2020 07:39:04 +0200 Subject: [PATCH] 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. --- .../services/amqp/activemq/default.nix | 8 +++-- nixos/modules/services/backup/syncoid.nix | 6 +++- .../services/cluster/hadoop/default.nix | 32 ++++++++++++------- .../services/network-filesystems/netatalk.nix | 5 +-- .../services/network-filesystems/rsyncd.nix | 5 +-- .../services/network-filesystems/samba.nix | 5 +-- nixos/modules/services/networking/3proxy.nix | 10 +++--- .../modules/services/networking/dnscache.nix | 10 +++--- nixos/modules/services/networking/ndppd.nix | 10 ++++-- .../services/networking/strongswan.nix | 30 +++++++++-------- .../modules/services/networking/syncthing.nix | 14 ++++---- nixos/modules/services/web-apps/youtrack.nix | 8 +++-- nixos/modules/virtualisation/containers.nix | 8 +++-- 13 files changed, 92 insertions(+), 59 deletions(-) diff --git a/nixos/modules/services/amqp/activemq/default.nix b/nixos/modules/services/amqp/activemq/default.nix index 7729da27304b..160dbddcd487 100644 --- a/nixos/modules/services/amqp/activemq/default.nix +++ b/nixos/modules/services/amqp/activemq/default.nix @@ -63,9 +63,11 @@ in { 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"; diff --git a/nixos/modules/services/backup/syncoid.nix b/nixos/modules/services/backup/syncoid.nix index 53787a0182af..fff119c2cf00 100644 --- a/nixos/modules/services/backup/syncoid.nix +++ b/nixos/modules/services/backup/syncoid.nix @@ -138,7 +138,11 @@ in { }; })); default = {}; - example."pool/test".target = "root@target:pool/test"; + example = literalExample '' + { + "pool/test".target = "root@target:pool/test"; + } + ''; description = "Syncoid commands to run."; }; }; diff --git a/nixos/modules/services/cluster/hadoop/default.nix b/nixos/modules/services/cluster/hadoop/default.nix index f0f5a6ecbfc5..bfb73f683715 100644 --- a/nixos/modules/services/cluster/hadoop/default.nix +++ b/nixos/modules/services/cluster/hadoop/default.nix @@ -7,33 +7,41 @@ with lib; 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"; }; diff --git a/nixos/modules/services/network-filesystems/netatalk.nix b/nixos/modules/services/network-filesystems/netatalk.nix index 1dd869043f0c..5422d4dd4e26 100644 --- a/nixos/modules/services/network-filesystems/netatalk.nix +++ b/nixos/modules/services/network-filesystems/netatalk.nix @@ -98,13 +98,14 @@ in Set of AFP volumes to export. See man apf.conf 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 { diff --git a/nixos/modules/services/network-filesystems/rsyncd.nix b/nixos/modules/services/network-filesystems/rsyncd.nix index b17ec3aa9300..ccad64cfdb2a 100644 --- a/nixos/modules/services/network-filesystems/rsyncd.nix +++ b/nixos/modules/services/network-filesystems/rsyncd.nix @@ -74,13 +74,14 @@ in See man rsyncd.conf for options. ''; type = types.attrsOf (types.attrsOf types.str); - example = + example = literalExample '' { srv = { path = "/srv"; "read only" = "yes"; comment = "Public rsync share."; }; - }; + } + ''; }; user = mkOption { diff --git a/nixos/modules/services/network-filesystems/samba.nix b/nixos/modules/services/network-filesystems/samba.nix index a3c22ce69484..a115590ccaa0 100644 --- a/nixos/modules/services/network-filesystems/samba.nix +++ b/nixos/modules/services/network-filesystems/samba.nix @@ -189,7 +189,7 @@ in See man smb.conf for options. ''; type = types.attrsOf (types.attrsOf types.unspecified); - example = + example = literalExample '' { public = { path = "/srv/public"; "read only" = true; @@ -197,7 +197,8 @@ in "guest ok" = "yes"; comment = "Public samba share."; }; - }; + } + ''; }; }; diff --git a/nixos/modules/services/networking/3proxy.nix b/nixos/modules/services/networking/3proxy.nix index 26aa16679467..ae8a4958ca96 100644 --- a/nixos/modules/services/networking/3proxy.nix +++ b/nixos/modules/services/networking/3proxy.nix @@ -334,10 +334,12 @@ in { 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."; }; }; diff --git a/nixos/modules/services/networking/dnscache.nix b/nixos/modules/services/networking/dnscache.nix index d123bca93219..d06032daecc7 100644 --- a/nixos/modules/services/networking/dnscache.nix +++ b/nixos/modules/services/networking/dnscache.nix @@ -61,10 +61,12 @@ in { 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 { diff --git a/nixos/modules/services/networking/ndppd.nix b/nixos/modules/services/networking/ndppd.nix index e015f76f622b..77e979a8a424 100644 --- a/nixos/modules/services/networking/ndppd.nix +++ b/nixos/modules/services/networking/ndppd.nix @@ -43,7 +43,7 @@ let 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; @@ -51,7 +51,7 @@ let 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; @@ -142,7 +142,11 @@ in { messages, and respond to them according to a set of rules. ''; default = {}; - example = { eth0.rules."1111::/64" = {}; }; + example = literalExample '' + { + eth0.rules."1111::/64" = {}; + } + ''; }; }; diff --git a/nixos/modules/services/networking/strongswan.nix b/nixos/modules/services/networking/strongswan.nix index 4ff9c486059c..13a1a897c5ed 100644 --- a/nixos/modules/services/networking/strongswan.nix +++ b/nixos/modules/services/networking/strongswan.nix @@ -4,7 +4,7 @@ let inherit (builtins) toFile; inherit (lib) concatMapStringsSep concatStringsSep mapAttrsToList - mkIf mkEnableOption mkOption types; + mkIf mkEnableOption mkOption types literalExample; cfg = config.services.strongswan; @@ -79,19 +79,21 @@ in 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 ipsec.conf file. diff --git a/nixos/modules/services/networking/syncthing.nix b/nixos/modules/services/networking/syncthing.nix index 5b3eb6f04b42..e717d78feed5 100644 --- a/nixos/modules/services/networking/syncthing.nix +++ b/nixos/modules/services/networking/syncthing.nix @@ -169,12 +169,14 @@ in { 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 = { diff --git a/nixos/modules/services/web-apps/youtrack.nix b/nixos/modules/services/web-apps/youtrack.nix index 830edac20bac..b4d653d2d77e 100644 --- a/nixos/modules/services/web-apps/youtrack.nix +++ b/nixos/modules/services/web-apps/youtrack.nix @@ -46,9 +46,11 @@ in 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; }; diff --git a/nixos/modules/virtualisation/containers.nix b/nixos/modules/virtualisation/containers.nix index 02de5801da25..dad211ef55ba 100644 --- a/nixos/modules/virtualisation/containers.nix +++ b/nixos/modules/virtualisation/containers.nix @@ -609,9 +609,11 @@ in 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 = ''