nixos/doc: clean up defaults and examples

18 files changed, 77 insertions, 65 deletions

diff --git a/nixos/modules/services/web-servers/apache-httpd/default.nix b/nixos/modules/services/web-servers/apache-httpd/default.nix
index ceb19987097..992a58875e4 100644
--- a/nixos/modules/services/web-servers/apache-httpd/default.nix
+++ b/nixos/modules/services/web-servers/apache-httpd/default.nix
@@ -407,7 +407,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.apacheHttpd;
-        defaultText = "pkgs.apacheHttpd";
+        defaultText = literalExpression "pkgs.apacheHttpd";
         description = ''
           Overridable attribute of the Apache HTTP Server package to use.
         '';
@@ -416,8 +416,8 @@ in
       configFile = mkOption {
         type = types.path;
         default = confFile;
-        defaultText = "confFile";
-        example = literalExample ''pkgs.writeText "httpd.conf" "# my custom config file ..."'';
+        defaultText = literalExpression "confFile";
+        example = literalExpression ''pkgs.writeText "httpd.conf" "# my custom config file ..."'';
         description = ''
           Override the configuration file used by Apache. By default,
           NixOS generates one automatically.
@@ -437,7 +437,7 @@ in
       extraModules = mkOption {
         type = types.listOf types.unspecified;
         default = [];
-        example = literalExample ''
+        example = literalExpression ''
           [
             "proxy_connect"
             { name = "jk"; path = "''${pkgs.tomcat_connectors}/modules/mod_jk.so"; }
@@ -516,7 +516,14 @@ in
             documentRoot = "${pkg}/htdocs";
           };
         };
-        example = literalExample ''
+        defaultText = literalExpression ''
+          {
+            localhost = {
+              documentRoot = "''${package.out}/htdocs";
+            };
+          }
+        '';
+        example = literalExpression ''
           {
             "foo.example.com" = {
               forceSSL = true;
@@ -550,7 +557,7 @@ in
       phpPackage = mkOption {
         type = types.package;
         default = pkgs.php;
-        defaultText = "pkgs.php";
+        defaultText = literalExpression "pkgs.php";
         description = ''
           Overridable attribute of the PHP package to use.
         '';
diff --git a/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix b/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix
index 3f732a5c9f3..8bb7e91ec9c 100644
--- a/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix
+++ b/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix
@@ -1,6 +1,6 @@
 { config, lib, name, ... }:
 let
-  inherit (lib) literalExample mkOption nameValuePair types;
+  inherit (lib) literalExpression mkOption nameValuePair types;
 in
 {
   options = {
@@ -266,7 +266,7 @@ in
     locations = mkOption {
       type = with types; attrsOf (submodule (import ./location-options.nix));
       default = {};
-      example = literalExample ''
+      example = literalExpression ''
         {
           "/" = {
             proxyPass = "http://localhost:3000";
diff --git a/nixos/modules/services/web-servers/caddy/default.nix b/nixos/modules/services/web-servers/caddy/default.nix
index fd710209634..cef27e2e59f 100644
--- a/nixos/modules/services/web-servers/caddy/default.nix
+++ b/nixos/modules/services/web-servers/caddy/default.nix
@@ -83,7 +83,7 @@ in
         inherit config lib;
       }));
       default = { };
-      example = literalExample ''
+      example = literalExpression ''
         {
           "hydra.example.com" = {
             serverAliases = [ "www.hydra.example.com" ];
@@ -162,8 +162,7 @@ in
 
     package = mkOption {
       default = pkgs.caddy;
-      defaultText = "pkgs.caddy";
-      example = "pkgs.caddy";
+      defaultText = literalExpression "pkgs.caddy";
       type = types.package;
       description = ''
         Caddy package to use.
diff --git a/nixos/modules/services/web-servers/lighttpd/cgit.nix b/nixos/modules/services/web-servers/lighttpd/cgit.nix
index 9f25dc34f3f..8cd6d020940 100644
--- a/nixos/modules/services/web-servers/lighttpd/cgit.nix
+++ b/nixos/modules/services/web-servers/lighttpd/cgit.nix
@@ -41,11 +41,13 @@ in
 
     configText = mkOption {
       default = "";
-      example = ''
-        source-filter=''${pkgs.cgit}/lib/cgit/filters/syntax-highlighting.py
-        about-filter=''${pkgs.cgit}/lib/cgit/filters/about-formatting.sh
-        cache-size=1000
-        scan-path=/srv/git
+      example = literalExpression ''
+        '''
+          source-filter=''${pkgs.cgit}/lib/cgit/filters/syntax-highlighting.py
+          about-filter=''${pkgs.cgit}/lib/cgit/filters/about-formatting.sh
+          cache-size=1000
+          scan-path=/srv/git
+        '''
       '';
       type = types.lines;
       description = ''
diff --git a/nixos/modules/services/web-servers/minio.nix b/nixos/modules/services/web-servers/minio.nix
index 6b10afad499..c345e3f2467 100644
--- a/nixos/modules/services/web-servers/minio.nix
+++ b/nixos/modules/services/web-servers/minio.nix
@@ -87,7 +87,7 @@ in
 
     package = mkOption {
       default = pkgs.minio;
-      defaultText = "pkgs.minio";
+      defaultText = literalExpression "pkgs.minio";
       type = types.package;
       description = "Minio package to use.";
     };
diff --git a/nixos/modules/services/web-servers/molly-brown.nix b/nixos/modules/services/web-servers/molly-brown.nix
index 58db9b9beda..0bd8b3316cb 100644
--- a/nixos/modules/services/web-servers/molly-brown.nix
+++ b/nixos/modules/services/web-servers/molly-brown.nix
@@ -22,8 +22,8 @@ in {
 
     hostName = mkOption {
       type = types.str;
-      example = literalExample "config.networking.hostName";
       default = config.networking.hostName;
+      defaultText = literalExpression "config.networking.hostName";
       description = ''
         The hostname to respond to requests for. Requests for URLs with
         other hosts will result in a status 53 (PROXY REQUEST REFUSED)
diff --git a/nixos/modules/services/web-servers/nginx/default.nix b/nixos/modules/services/web-servers/nginx/default.nix
index 6682472fdb8..d5486be65ee 100644
--- a/nixos/modules/services/web-servers/nginx/default.nix
+++ b/nixos/modules/services/web-servers/nginx/default.nix
@@ -425,7 +425,7 @@ in
 
       package = mkOption {
         default = pkgs.nginxStable;
-        defaultText = "pkgs.nginxStable";
+        defaultText = literalExpression "pkgs.nginxStable";
         type = types.package;
         apply = p: p.override {
           modules = p.modules ++ cfg.additionalModules;
@@ -440,7 +440,7 @@ in
       additionalModules = mkOption {
         default = [];
         type = types.listOf (types.attrsOf types.anything);
-        example = literalExample "[ pkgs.nginxModules.brotli ]";
+        example = literalExpression "[ pkgs.nginxModules.brotli ]";
         description = ''
           Additional <link xlink:href="https://www.nginx.com/resources/wiki/modules/">third-party nginx modules</link>
           to install. Packaged modules are available in
@@ -674,7 +674,7 @@ in
             addresses = mkOption {
               type = types.listOf types.str;
               default = [];
-              example = literalExample ''[ "[::1]" "127.0.0.1:5353" ]'';
+              example = literalExpression ''[ "[::1]" "127.0.0.1:5353" ]'';
               description = "List of resolvers to use";
             };
             valid = mkOption {
@@ -738,7 +738,7 @@ in
           Defines a group of servers to use as proxy target.
         '';
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
           "backend_server" = {
             servers = { "127.0.0.1:8000" = {}; };
             extraConfig = ''''
@@ -755,7 +755,7 @@ in
         default = {
           localhost = {};
         };
-        example = literalExample ''
+        example = literalExpression ''
           {
             "hydra.example.com" = {
               forceSSL = true;
diff --git a/nixos/modules/services/web-servers/nginx/location-options.nix b/nixos/modules/services/web-servers/nginx/location-options.nix
index d8c976f202f..56a5381e05c 100644
--- a/nixos/modules/services/web-servers/nginx/location-options.nix
+++ b/nixos/modules/services/web-servers/nginx/location-options.nix
@@ -12,7 +12,7 @@ with lib;
     basicAuth = mkOption {
       type = types.attrsOf types.str;
       default = {};
-      example = literalExample ''
+      example = literalExpression ''
         {
           user = "password";
         };
diff --git a/nixos/modules/services/web-servers/nginx/vhost-options.nix b/nixos/modules/services/web-servers/nginx/vhost-options.nix
index 94645e927f8..7ee041d3721 100644
--- a/nixos/modules/services/web-servers/nginx/vhost-options.nix
+++ b/nixos/modules/services/web-servers/nginx/vhost-options.nix
@@ -162,7 +162,7 @@ with lib;
     sslTrustedCertificate = mkOption {
       type = types.nullOr types.path;
       default = null;
-      example = "\${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";
+      example = literalExpression ''"''${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"'';
       description = "Path to root SSL certificate for stapling and client certificates.";
     };
 
@@ -231,7 +231,7 @@ with lib;
     basicAuth = mkOption {
       type = types.attrsOf types.str;
       default = {};
-      example = literalExample ''
+      example = literalExpression ''
         {
           user = "password";
         };
@@ -261,7 +261,7 @@ with lib;
         inherit lib;
       }));
       default = {};
-      example = literalExample ''
+      example = literalExpression ''
         {
           "/" = {
             proxyPass = "http://localhost:3000";
diff --git a/nixos/modules/services/web-servers/phpfpm/default.nix b/nixos/modules/services/web-servers/phpfpm/default.nix
index 4d302299f5f..87c68fa074a 100644
--- a/nixos/modules/services/web-servers/phpfpm/default.nix
+++ b/nixos/modules/services/web-servers/phpfpm/default.nix
@@ -59,7 +59,7 @@ let
         phpPackage = mkOption {
           type = types.package;
           default = cfg.phpPackage;
-          defaultText = "config.services.phpfpm.phpPackage";
+          defaultText = literalExpression "config.services.phpfpm.phpPackage";
           description = ''
             The PHP package to use for running this PHP-FPM pool.
           '';
@@ -78,7 +78,7 @@ let
           description = ''
             Environment variables used for this PHP-FPM pool.
           '';
-          example = literalExample ''
+          example = literalExpression ''
             {
               HOSTNAME = "$HOSTNAME";
               TMP = "/tmp";
@@ -107,7 +107,7 @@ let
             for details. Note that settings names must be enclosed in quotes (e.g.
             <literal>"pm.max_children"</literal> instead of <literal>pm.max_children</literal>).
           '';
-          example = literalExample ''
+          example = literalExpression ''
             {
               "pm" = "dynamic";
               "pm.max_children" = 75;
@@ -179,7 +179,7 @@ in {
       phpPackage = mkOption {
         type = types.package;
         default = pkgs.php;
-        defaultText = "pkgs.php";
+        defaultText = literalExpression "pkgs.php";
         description = ''
           The PHP package to use for running the PHP-FPM service.
         '';
@@ -200,7 +200,7 @@ in {
       pools = mkOption {
         type = types.attrsOf (types.submodule poolOpts);
         default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            mypool = {
              user = "php";
diff --git a/nixos/modules/services/web-servers/tomcat.nix b/nixos/modules/services/web-servers/tomcat.nix
index 13fe98402c6..f9446fe125a 100644
--- a/nixos/modules/services/web-servers/tomcat.nix
+++ b/nixos/modules/services/web-servers/tomcat.nix
@@ -24,8 +24,8 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.tomcat85;
-        defaultText = "pkgs.tomcat85";
-        example = lib.literalExample "pkgs.tomcat9";
+        defaultText = literalExpression "pkgs.tomcat85";
+        example = lib.literalExpression "pkgs.tomcat9";
         description = ''
           Which tomcat package to use.
         '';
@@ -127,7 +127,7 @@ in
       webapps = mkOption {
         type = types.listOf types.path;
         default = [ tomcat.webapps ];
-        defaultText = "[ pkgs.tomcat85.webapps ]";
+        defaultText = literalExpression "[ pkgs.tomcat85.webapps ]";
         description = "List containing WAR files or directories with WAR files which are web applications to be deployed on Tomcat";
       };
 
@@ -166,7 +166,7 @@ in
       jdk = mkOption {
         type = types.package;
         default = pkgs.jdk;
-        defaultText = "pkgs.jdk";
+        defaultText = literalExpression "pkgs.jdk";
         description = "Which JDK to use.";
       };
 
diff --git a/nixos/modules/services/web-servers/traefik.nix b/nixos/modules/services/web-servers/traefik.nix
index 3d29199dd45..eb7fd0995de 100644
--- a/nixos/modules/services/web-servers/traefik.nix
+++ b/nixos/modules/services/web-servers/traefik.nix
@@ -54,7 +54,7 @@ in {
 
     staticConfigFile = mkOption {
       default = null;
-      example = literalExample "/path/to/static_config.toml";
+      example = literalExpression "/path/to/static_config.toml";
       type = types.nullOr types.path;
       description = ''
         Path to traefik's static configuration to use.
@@ -78,7 +78,7 @@ in {
 
     dynamicConfigFile = mkOption {
       default = null;
-      example = literalExample "/path/to/dynamic_config.toml";
+      example = literalExpression "/path/to/dynamic_config.toml";
       type = types.nullOr types.path;
       description = ''
         Path to traefik's dynamic configuration to use.
@@ -123,7 +123,7 @@ in {
 
     package = mkOption {
       default = pkgs.traefik;
-      defaultText = "pkgs.traefik";
+      defaultText = literalExpression "pkgs.traefik";
       type = types.package;
       description = "Traefik package to use.";
     };
diff --git a/nixos/modules/services/web-servers/trafficserver/default.nix b/nixos/modules/services/web-servers/trafficserver/default.nix
index 341e8b13976..706ea5bfefb 100644
--- a/nixos/modules/services/web-servers/trafficserver/default.nix
+++ b/nixos/modules/services/web-servers/trafficserver/default.nix
@@ -62,15 +62,17 @@ in
     ipAllow = mkOption {
       type = types.nullOr yaml.type;
       default = builtins.fromJSON (builtins.readFile ./ip_allow.json);
-      defaultText = "upstream defaults";
-      example = literalExample {
-        ip_allow = [{
-          apply = "in";
-          ip_addrs = "127.0.0.1";
-          action = "allow";
-          methods = "ALL";
-        }];
-      };
+      defaultText = literalDocBook "upstream defaults";
+      example = literalExpression ''
+        {
+          ip_allow = [{
+            apply = "in";
+            ip_addrs = "127.0.0.1";
+            action = "allow";
+            methods = "ALL";
+          }];
+        }
+      '';
       description = ''
         Control client access to Traffic Server and Traffic Server connections
         to upstream servers.
@@ -83,8 +85,8 @@ in
     logging = mkOption {
       type = types.nullOr yaml.type;
       default = builtins.fromJSON (builtins.readFile ./logging.json);
-      defaultText = "upstream defaults";
-      example = literalExample { };
+      defaultText = literalDocBook "upstream defaults";
+      example = { };
       description = ''
         Configure logs.
 
@@ -145,7 +147,7 @@ in
         in
         valueType;
       default = { };
-      example = literalExample { proxy.config.proxy_name = "my_server"; };
+      example = { proxy.config.proxy_name = "my_server"; };
       description = ''
         List of configurable variables used by Traffic Server.
 
@@ -197,12 +199,14 @@ in
     sni = mkOption {
       type = types.nullOr yaml.type;
       default = null;
-      example = literalExample {
-        sni = [{
-          fqdn = "no-http2.example.com";
-          https = "off";
-        }];
-      };
+      example = literalExpression ''
+        {
+          sni = [{
+            fqdn = "no-http2.example.com";
+            https = "off";
+          }];
+        }
+      '';
       description = ''
         Configure aspects of TLS connection handling for both inbound and
         outbound connections.
diff --git a/nixos/modules/services/web-servers/ttyd.nix b/nixos/modules/services/web-servers/ttyd.nix
index 68d55ee6ffd..431509f7fd5 100644
--- a/nixos/modules/services/web-servers/ttyd.nix
+++ b/nixos/modules/services/web-servers/ttyd.nix
@@ -78,7 +78,7 @@ in
       clientOptions = mkOption {
         type = types.attrsOf types.str;
         default = {};
-        example = literalExample ''{
+        example = literalExpression ''{
           fontSize = "16";
           fontFamily = "Fira Code";
 
diff --git a/nixos/modules/services/web-servers/unit/default.nix b/nixos/modules/services/web-servers/unit/default.nix
index 2a264bf2e9a..b2eecdbb53e 100644
--- a/nixos/modules/services/web-servers/unit/default.nix
+++ b/nixos/modules/services/web-servers/unit/default.nix
@@ -14,7 +14,7 @@ in {
       package = mkOption {
         type = types.package;
         default = pkgs.unit;
-        defaultText = "pkgs.unit";
+        defaultText = literalExpression "pkgs.unit";
         description = "Unit package to use.";
       };
       user = mkOption {
@@ -45,7 +45,7 @@ in {
             "applications": {}
           }
         '';
-        example = literalExample ''
+        example = ''
           {
             "listeners": {
               "*:8300": {
diff --git a/nixos/modules/services/web-servers/uwsgi.nix b/nixos/modules/services/web-servers/uwsgi.nix
index 2dfc39c847a..ac435951310 100644
--- a/nixos/modules/services/web-servers/uwsgi.nix
+++ b/nixos/modules/services/web-servers/uwsgi.nix
@@ -114,7 +114,7 @@ in {
         default = {
           type = "normal";
         };
-        example = literalExample ''
+        example = literalExpression ''
           {
             type = "emperor";
             vassals = {
@@ -163,7 +163,7 @@ in {
         type = types.listOf types.str;
         apply = caps: caps ++ optionals isEmperor imperialPowers;
         default = [ ];
-        example = literalExample ''
+        example = literalExpression ''
           [
             "CAP_NET_BIND_SERVICE" # bind on ports <1024
             "CAP_NET_RAW"          # open raw sockets
diff --git a/nixos/modules/services/web-servers/varnish/default.nix b/nixos/modules/services/web-servers/varnish/default.nix
index 01fe3d12917..7597b80baf6 100644
--- a/nixos/modules/services/web-servers/varnish/default.nix
+++ b/nixos/modules/services/web-servers/varnish/default.nix
@@ -16,7 +16,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.varnish;
-        defaultText = "pkgs.varnish";
+        defaultText = literalExpression "pkgs.varnish";
         description = ''
           The package to use
         '';
@@ -48,7 +48,7 @@ in
       extraModules = mkOption {
         type = types.listOf types.package;
         default = [];
-        example = literalExample "[ pkgs.varnishPackages.geoip ]";
+        example = literalExpression "[ pkgs.varnishPackages.geoip ]";
         description = "
           Varnish modules (except 'std').
         ";
diff --git a/nixos/modules/services/web-servers/zope2.nix b/nixos/modules/services/web-servers/zope2.nix
index ab12e87502e..92210916022 100644
--- a/nixos/modules/services/web-servers/zope2.nix
+++ b/nixos/modules/services/web-servers/zope2.nix
@@ -75,7 +75,7 @@ in
     services.zope2.instances = mkOption {
       default = {};
       type = with types; attrsOf (submodule zope2Opts);
-      example = literalExample ''
+      example = literalExpression ''
         {
           plone01 = {
             http_address = "127.0.0.1:8080";