alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

nixos/treewide: Fix incorrectly rendered examples

Browse source 
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.
This commit is contained in:
Silvan Mosberger 2020-04-02 07:39:04 +02:00
parent f75c11cfdf
commit 1d0fc9729d
No known key found for this signature in database
GPG key ID: E8F1E9EAD284E17D
13 changed files with 92 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
nixos/modules/services/amqp/activemq/default.nix
View file

@ -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";

6
nixos/modules/services/backup/syncoid.nix
View file

@ -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.";
};
};

32
nixos/modules/services/cluster/hadoop/default.nix
View file

@ -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";
};

5
nixos/modules/services/network-filesystems/netatalk.nix
View file

@ -98,13 +98,14 @@ in
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 {

5
nixos/modules/services/network-filesystems/rsyncd.nix
View file

@ -74,13 +74,14 @@ in
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 {

5
nixos/modules/services/network-filesystems/samba.nix
View file

@ -189,7 +189,7 @@ in
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;
@ -197,7 +197,8 @@ in
"guest ok" = "yes";
comment = "Public samba share.";
};
};
}
'';
};
};

10
nixos/modules/services/networking/3proxy.nix
View file

@ -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.";
};
};

10
nixos/modules/services/networking/dnscache.nix
View file

@ -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 {

6
nixos/modules/services/networking/ndppd.nix
View file

@ -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" = {};
}
'';
};
};

30
nixos/modules/services/networking/strongswan.nix
View file

@ -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 <filename>ipsec.conf</filename> file.

14
nixos/modules/services/networking/syncthing.nix
View file

@ -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 = {

8
nixos/modules/services/web-apps/youtrack.nix
View file

@ -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;
};

8
nixos/modules/virtualisation/containers.nix
View file

@ -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 =
''