nixos/doc: clean up defaults and examples

NixOS · Oct 4, 2021 · 2ddc335 · 2ddc335
1 parent 330b1e0
commit 2ddc335
Show file tree

Hide file tree

Showing 584 changed files with 1,612 additions and 1,554 deletions.
diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md
@@ -38,9 +38,19 @@ The function `mkOption` accepts the following arguments.
     of the module will have to define the value of the option, otherwise
     an error will be thrown.
 
+`defaultText`
+
+:   A textual representation of the default value to be rendered verbatim in
+    the manual. Useful if the default value is a complex expression or depends
+    on other values or packages.
+    Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for
+    a plain English description in DocBook format.
+
 `example`
 
 :   An example value that will be shown in the NixOS manual.
+    You can use `lib.literalExpression` and `lib.literalDocBook` in the same way
+    as in `defaultText`.
 
 `description`
 

diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml
@@ -57,13 +57,31 @@ options = {
         </para>
       </listitem>
     </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>defaultText</literal>
+      </term>
+      <listitem>
+        <para>
+          A textual representation of the default value to be rendered
+          verbatim in the manual. Useful if the default value is a
+          complex expression or depends on other values or packages. Use
+          <literal>lib.literalExpression</literal> for a Nix expression,
+          <literal>lib.literalDocBook</literal> for a plain English
+          description in DocBook format.
+        </para>
+      </listitem>
+    </varlistentry>
     <varlistentry>
       <term>
         <literal>example</literal>
       </term>
       <listitem>
         <para>
-          An example value that will be shown in the NixOS manual.
+          An example value that will be shown in the NixOS manual. You
+          can use <literal>lib.literalExpression</literal> and
+          <literal>lib.literalDocBook</literal> in the same way as in
+          <literal>defaultText</literal>.
         </para>
       </listitem>
     </varlistentry>

diff --git a/nixos/maintainers/scripts/ec2/amazon-image.nix b/nixos/maintainers/scripts/ec2/amazon-image.nix
@@ -27,7 +27,7 @@ in {
     };
 
     contents = mkOption {
-      example = literalExample ''
+      example = literalExpression ''
         [ { source = pkgs.memtest86 + "/memtest.bin";
             target = "boot/memtest.bin";
           }

diff --git a/nixos/modules/config/fonts/fonts.nix b/nixos/modules/config/fonts/fonts.nix
@@ -61,7 +61,7 @@ in
       fonts = mkOption {
         type = types.listOf types.path;
         default = [];
-        example = literalExample "[ pkgs.dejavu_fonts ]";
+        example = literalExpression "[ pkgs.dejavu_fonts ]";
         description = "List of primary font paths.";
       };
 

diff --git a/nixos/modules/config/i18n.nix b/nixos/modules/config/i18n.nix
@@ -14,7 +14,7 @@ with lib;
           allLocales = any (x: x == "all") config.i18n.supportedLocales;
           locales = config.i18n.supportedLocales;
         };
-        example = literalExample "pkgs.glibcLocales";
+        example = literalExpression "pkgs.glibcLocales";
         description = ''
           Customized pkg.glibcLocales package.
 

diff --git a/nixos/modules/config/krb5/default.nix b/nixos/modules/config/krb5/default.nix
@@ -83,8 +83,8 @@ in {
       kerberos = mkOption {
         type = types.package;
         default = pkgs.krb5Full;
-        defaultText = "pkgs.krb5Full";
-        example = literalExample "pkgs.heimdal";
+        defaultText = literalExpression "pkgs.krb5Full";
+        example = literalExpression "pkgs.heimdal";
         description = ''
           The Kerberos implementation that will be present in
           <literal>environment.systemPackages</literal> after enabling this
@@ -96,7 +96,7 @@ in {
         type = with types; either attrs lines;
         default = {};
         apply = attrs: filterEmbeddedMetadata attrs;
-        example = literalExample ''
+        example = literalExpression ''
           {
             default_realm = "ATHENA.MIT.EDU";
           };
@@ -109,7 +109,7 @@ in {
       realms = mkOption {
         type = with types; either attrs lines;
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
           {
             "ATHENA.MIT.EDU" = {
               admin_server = "athena.mit.edu";
@@ -127,7 +127,7 @@ in {
       domain_realm = mkOption {
         type = with types; either attrs lines;
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
           {
             "example.com" = "EXAMPLE.COM";
             ".example.com" = "EXAMPLE.COM";
@@ -142,7 +142,7 @@ in {
       capaths = mkOption {
         type = with types; either attrs lines;
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
           {
             "ATHENA.MIT.EDU" = {
               "EXAMPLE.COM" = ".";
@@ -161,7 +161,7 @@ in {
       appdefaults = mkOption {
         type = with types; either attrs lines;
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
           {
             pam = {
               debug = false;
@@ -182,7 +182,7 @@ in {
       plugins = mkOption {
         type = with types; either attrs lines;
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
           {
             ccselect = {
               disable = "k5identity";

diff --git a/nixos/modules/config/networking.nix b/nixos/modules/config/networking.nix
@@ -21,7 +21,7 @@ in
 
     networking.hosts = lib.mkOption {
       type = types.attrsOf (types.listOf types.str);
-      example = literalExample ''
+      example = literalExpression ''
         {
           "127.0.0.1" = [ "foo.bar.baz" ];
           "192.168.0.2" = [ "fileserver.local" "nameserver.local" ];
@@ -34,8 +34,8 @@ in
 
     networking.hostFiles = lib.mkOption {
       type = types.listOf types.path;
-      defaultText = lib.literalExample "Hosts from `networking.hosts` and `networking.extraHosts`";
-      example = lib.literalExample ''[ "''${pkgs.my-blocklist-package}/share/my-blocklist/hosts" ]'';
+      defaultText = literalDocBook "Hosts from <option>networking.hosts</option> and <option>networking.extraHosts</option>";
+      example = literalExpression ''[ "''${pkgs.my-blocklist-package}/share/my-blocklist/hosts" ]'';
       description = ''
         Files that should be concatenated together to form <filename>/etc/hosts</filename>.
       '';

diff --git a/nixos/modules/config/power-management.nix b/nixos/modules/config/power-management.nix
@@ -35,7 +35,7 @@ in
       powerUpCommands = mkOption {
         type = types.lines;
         default = "";
-        example = literalExample ''
+        example = literalExpression ''
           "''${pkgs.hdparm}/sbin/hdparm -B 255 /dev/sda"
         '';
         description =
@@ -49,7 +49,7 @@ in
       powerDownCommands = mkOption {
         type = types.lines;
         default = "";
-        example = literalExample ''
+        example = literalExpression ''
           "''${pkgs.hdparm}/sbin/hdparm -B 255 /dev/sda"
         '';
         description =

diff --git a/nixos/modules/config/pulseaudio.nix b/nixos/modules/config/pulseaudio.nix
@@ -149,8 +149,8 @@ in {
         default = if config.services.jack.jackd.enable
                   then pkgs.pulseaudioFull
                   else pkgs.pulseaudio;
-        defaultText = "pkgs.pulseaudio";
-        example = literalExample "pkgs.pulseaudioFull";
+        defaultText = literalExpression "pkgs.pulseaudio";
+        example = literalExpression "pkgs.pulseaudioFull";
         description = ''
           The PulseAudio derivation to use.  This can be used to enable
           features (such as JACK support, Bluetooth) via the
@@ -161,7 +161,7 @@ in {
       extraModules = mkOption {
         type = types.listOf types.package;
         default = [];
-        example = literalExample "[ pkgs.pulseaudio-modules-bt ]";
+        example = literalExpression "[ pkgs.pulseaudio-modules-bt ]";
         description = ''
           Extra pulseaudio modules to use. This is intended for out-of-tree
           pulseaudio modules like extra bluetooth codecs.
@@ -184,7 +184,7 @@ in {
           type = types.attrsOf types.unspecified;
           default = {};
           description = "Config of the pulse daemon. See <literal>man pulse-daemon.conf</literal>.";
-          example = literalExample ''{ realtime-scheduling = "yes"; }'';
+          example = literalExpression ''{ realtime-scheduling = "yes"; }'';
         };
       };
 
@@ -204,7 +204,7 @@ in {
           allowedIpRanges = mkOption {
             type = types.listOf types.str;
             default = [];
-            example = literalExample ''[ "127.0.0.1" "192.168.1.0/24" ]'';
+            example = literalExpression ''[ "127.0.0.1" "192.168.1.0/24" ]'';
             description = ''
               A list of IP subnets that are allowed to stream to the server.
             '';

diff --git a/nixos/modules/config/shells-environment.nix b/nixos/modules/config/shells-environment.nix
@@ -136,10 +136,8 @@ in
 
     environment.binsh = mkOption {
       default = "${config.system.build.binsh}/bin/sh";
-      defaultText = "\${config.system.build.binsh}/bin/sh";
-      example = literalExample ''
-        "''${pkgs.dash}/bin/dash"
-      '';
+      defaultText = literalExpression ''"''${config.system.build.binsh}/bin/sh"'';
+      example = literalExpression ''"''${pkgs.dash}/bin/dash"'';
       type = types.path;
       visible = false;
       description = ''
@@ -152,7 +150,7 @@ in
 
     environment.shells = mkOption {
       default = [];
-      example = literalExample "[ pkgs.bashInteractive pkgs.zsh ]";
+      example = literalExpression "[ pkgs.bashInteractive pkgs.zsh ]";
       description = ''
         A list of permissible login shells for user accounts.
         No need to mention <literal>/bin/sh</literal>

diff --git a/nixos/modules/config/sysctl.nix b/nixos/modules/config/sysctl.nix
@@ -22,7 +22,7 @@ in
 
     boot.kernel.sysctl = mkOption {
       default = {};
-      example = literalExample ''
+      example = literalExpression ''
         { "net.ipv4.tcp_syncookies" = false; "vm.swappiness" = 60; }
       '';
       type = types.attrsOf sysctlOption;

diff --git a/nixos/modules/config/system-path.nix b/nixos/modules/config/system-path.nix
@@ -58,7 +58,7 @@ in
       systemPackages = mkOption {
         type = types.listOf types.package;
         default = [];
-        example = literalExample "[ pkgs.firefox pkgs.thunderbird ]";
+        example = literalExpression "[ pkgs.firefox pkgs.thunderbird ]";
         description = ''
           The set of packages that appear in
           /run/current-system/sw.  These packages are
@@ -73,9 +73,9 @@ in
       defaultPackages = mkOption {
         type = types.listOf types.package;
         default = defaultPackages;
-        example = literalExample "[]";
+        example = [];
         description = ''
-          Set of default packages that aren't strictly neccessary
+          Set of default packages that aren't strictly necessary
           for a running system, entries can be removed for a more
           minimal NixOS installation.
 

diff --git a/nixos/modules/config/unix-odbc-drivers.nix b/nixos/modules/config/unix-odbc-drivers.nix
@@ -19,7 +19,7 @@ in {
     environment.unixODBCDrivers = mkOption {
       type = types.listOf types.package;
       default = [];
-      example = literalExample "with pkgs.unixODBCDrivers; [ sqlite psql ]";
+      example = literalExpression "with pkgs.unixODBCDrivers; [ sqlite psql ]";
       description = ''
         Specifies Unix ODBC drivers to be registered in
         <filename>/etc/odbcinst.ini</filename>.  You may also want to

diff --git a/nixos/modules/config/users-groups.nix b/nixos/modules/config/users-groups.nix
@@ -165,8 +165,8 @@ let
       shell = mkOption {
         type = types.nullOr (types.either types.shellPackage (passwdEntry types.path));
         default = pkgs.shadow;
-        defaultText = "pkgs.shadow";
-        example = literalExample "pkgs.bashInteractive";
+        defaultText = literalExpression "pkgs.shadow";
+        example = literalExpression "pkgs.bashInteractive";
         description = ''
           The path to the user's shell. Can use shell derivations,
           like <literal>pkgs.bashInteractive</literal>. Don’t
@@ -291,7 +291,7 @@ let
       packages = mkOption {
         type = types.listOf types.package;
         default = [];
-        example = literalExample "[ pkgs.firefox pkgs.thunderbird ]";
+        example = literalExpression "[ pkgs.firefox pkgs.thunderbird ]";
         description = ''
           The set of packages that should be made available to the user.
           This is in contrast to <option>environment.systemPackages</option>,

diff --git a/nixos/modules/config/xdg/portals/wlr.nix b/nixos/modules/config/xdg/portals/wlr.nix
@@ -37,7 +37,7 @@ in
       default = { };
 
       # Example taken from the manpage
-      example = literalExample ''
+      example = literalExpression ''
         {
           screencast = {
             output_name = "HDMI-A-1";

diff --git a/nixos/modules/hardware/ckb-next.nix b/nixos/modules/hardware/ckb-next.nix
@@ -27,7 +27,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.ckb-next;
-        defaultText = "pkgs.ckb-next";
+        defaultText = literalExpression "pkgs.ckb-next";
         description = ''
           The package implementing the Corsair keyboard/mouse driver.
         '';

diff --git a/nixos/modules/hardware/device-tree.nix b/nixos/modules/hardware/device-tree.nix
@@ -21,7 +21,7 @@ let
           each .dtb file matching "compatible" of the overlay.
         '';
         default = null;
-        example = literalExample "./dts/overlays.dts";
+        example = literalExpression "./dts/overlays.dts";
       };
 
       dtsText = mkOption {
@@ -31,7 +31,7 @@ let
           Literal DTS contents, overlay is applied to
           each .dtb file matching "compatible" of the overlay.
         '';
-        example = literalExample ''
+        example = ''
           /dts-v1/;
           /plugin/;
           / {
@@ -125,8 +125,8 @@ in
 
         kernelPackage = mkOption {
           default = config.boot.kernelPackages.kernel;
-          defaultText = "config.boot.kernelPackages.kernel";
-          example = literalExample "pkgs.linux_latest";
+          defaultText = literalExpression "config.boot.kernelPackages.kernel";
+          example = literalExpression "pkgs.linux_latest";
           type = types.path;
           description = ''
             Kernel package containing the base device-tree (.dtb) to boot. Uses
@@ -156,7 +156,7 @@ in
 
         overlays = mkOption {
           default = [];
-          example = literalExample ''
+          example = literalExpression ''
             [
               { name = "pps"; dtsFile = ./dts/pps.dts; }
               { name = "spi";

diff --git a/nixos/modules/hardware/digitalbitbox.nix b/nixos/modules/hardware/digitalbitbox.nix
@@ -19,7 +19,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.digitalbitbox;
-      defaultText = "pkgs.digitalbitbox";
+      defaultText = literalExpression "pkgs.digitalbitbox";
       description = "The Digital Bitbox package to use. This can be used to install a package with udev rules that differ from the defaults.";
     };
   };

diff --git a/nixos/modules/hardware/opengl.nix b/nixos/modules/hardware/opengl.nix
@@ -89,7 +89,7 @@ in
       extraPackages = mkOption {
         type = types.listOf types.package;
         default = [];
-        example = literalExample "with pkgs; [ vaapiIntel libvdpau-va-gl vaapiVdpau intel-ocl ]";
+        example = literalExpression "with pkgs; [ vaapiIntel libvdpau-va-gl vaapiVdpau intel-ocl ]";
         description = ''
           Additional packages to add to OpenGL drivers. This can be used
           to add OpenCL drivers, VA-API/VDPAU drivers etc.
@@ -99,7 +99,7 @@ in
       extraPackages32 = mkOption {
         type = types.listOf types.package;
         default = [];
-        example = literalExample "with pkgs.pkgsi686Linux; [ vaapiIntel libvdpau-va-gl vaapiVdpau ]";
+        example = literalExpression "with pkgs.pkgsi686Linux; [ vaapiIntel libvdpau-va-gl vaapiVdpau ]";
         description = ''
           Additional packages to add to 32-bit OpenGL drivers on
           64-bit systems. Used when <option>driSupport32Bit</option> is

diff --git a/nixos/modules/hardware/opentabletdriver.nix b/nixos/modules/hardware/opentabletdriver.nix
@@ -29,7 +29,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.opentabletdriver;
-        defaultText = "pkgs.opentabletdriver";
+        defaultText = literalExpression "pkgs.opentabletdriver";
         description = ''
           OpenTabletDriver derivation to use.
         '';