nixos/doc: fix some options

31 files changed, 67 insertions, 60 deletions

diff --git a/nixos/modules/programs/htop.nix b/nixos/modules/programs/htop.nix
index 521287f9352d..2682ced490ca 100644
--- a/nixos/modules/programs/htop.nix
+++ b/nixos/modules/programs/htop.nix
@@ -20,7 +20,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.htop;
-      defaultText = "pkgs.htop";
+      defaultText = lib.literalExpression "pkgs.htop";
       description = lib.mdDoc ''
         The htop package that should be used.
       '';
diff --git a/nixos/modules/programs/weylus.nix b/nixos/modules/programs/weylus.nix
index eab8afdf2cc8..a5775f3b981c 100644
--- a/nixos/modules/programs/weylus.nix
+++ b/nixos/modules/programs/weylus.nix
@@ -29,7 +29,7 @@ in
     package = mkOption {
       type = package;
       default = pkgs.weylus;
-      defaultText = "pkgs.weylus";
+      defaultText = lib.literalExpression "pkgs.weylus";
       description = lib.mdDoc "Weylus package to install.";
     };
   };
diff --git a/nixos/modules/services/audio/liquidsoap.nix b/nixos/modules/services/audio/liquidsoap.nix
index c313104c4609..5c10d13af5fd 100644
--- a/nixos/modules/services/audio/liquidsoap.nix
+++ b/nixos/modules/services/audio/liquidsoap.nix
@@ -38,11 +38,13 @@ in
 
       default = {};
 
-      example = {
-        myStream1 = "/etc/liquidsoap/myStream1.liq";
-        myStream2 = literalExpression "./myStream2.liq";
-        myStream3 = "out(playlist(\"/srv/music/\"))";
-      };
+      example = literalExpression ''
+        {
+          myStream1 = "/etc/liquidsoap/myStream1.liq";
+          myStream2 = ./myStream2.liq;
+          myStream3 = "out(playlist(\"/srv/music/\"))";
+        }
+      '';
 
       type = types.attrsOf (types.either types.path types.str);
     };
diff --git a/nixos/modules/services/databases/clickhouse.nix b/nixos/modules/services/databases/clickhouse.nix
index 96607d9a783c..04dd20b5f14d 100644
--- a/nixos/modules/services/databases/clickhouse.nix
+++ b/nixos/modules/services/databases/clickhouse.nix
@@ -16,7 +16,7 @@ with lib;
       package = mkOption {
         type = types.package;
         default = pkgs.clickhouse;
-        defaultText = "pkgs.clickhouse";
+        defaultText = lib.literalExpression "pkgs.clickhouse";
         description = lib.mdDoc ''
           ClickHouse package to use.
         '';
diff --git a/nixos/modules/services/databases/mysql.nix b/nixos/modules/services/databases/mysql.nix
index ec4524e9061d..128bb0862175 100644
--- a/nixos/modules/services/databases/mysql.nix
+++ b/nixos/modules/services/databases/mysql.nix
@@ -160,10 +160,12 @@ in
           List of database names and their initial schemas that should be used to create databases on the first startup
           of MySQL. The schema attribute is optional: If not specified, an empty database is created.
         '';
-        example = [
-          { name = "foodatabase"; schema = literalExpression "./foodatabase.sql"; }
-          { name = "bardatabase"; }
-        ];
+        example = literalExpression ''
+          [
+            { name = "foodatabase"; schema = ./foodatabase.sql; }
+            { name = "bardatabase"; }
+          ]
+        '';
       };
 
       initialScript = mkOption {
diff --git a/nixos/modules/services/databases/openldap.nix b/nixos/modules/services/databases/openldap.nix
index 7a59de372f24..cba3442023cb 100644
--- a/nixos/modules/services/databases/openldap.nix
+++ b/nixos/modules/services/databases/openldap.nix
@@ -16,7 +16,7 @@ let
       # systemd/systemd#19604
       description = ''
         LDAP value - either a string, or an attrset containing
-        <literal>path</literal> or <literal>base64</literal> for included
+        `path` or `base64` for included
         values or base-64 encoded values respectively.
       '';
       check = x: lib.isString x || (lib.isAttrs x && (x ? path || x ? base64));
diff --git a/nixos/modules/services/games/asf.nix b/nixos/modules/services/games/asf.nix
index 10847e8f11f3..d3f7883421ce 100644
--- a/nixos/modules/services/games/asf.nix
+++ b/nixos/modules/services/games/asf.nix
@@ -43,12 +43,14 @@ in
     web-ui = mkOption {
       type = types.submodule {
         options = {
-          enable = mkEnableOption
-            (lib.mdDoc "Wheter to start the web-ui. This is the preferred way of configuring things such as the steam guard token");
+          enable = mkEnableOption "" // {
+            description = lib.mdDoc "Whether to start the web-ui. This is the preferred way of configuring things such as the steam guard token.";
+          };
 
           package = mkOption {
             type = types.package;
             default = pkgs.ArchiSteamFarm.ui;
+            defaultText = lib.literalExpression "pkgs.ArchiSteamFarm.ui";
             description =
               lib.mdDoc "Web-UI package to use. Contents must be in lib/dist.";
           };
@@ -56,7 +58,6 @@ in
       };
       default = {
         enable = true;
-        package = pkgs.ArchiSteamFarm.ui;
       };
       example = {
         enable = false;
@@ -67,6 +68,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.ArchiSteamFarm;
+      defaultText = lib.literalExpression "pkgs.ArchiSteamFarm";
       description =
         lib.mdDoc "Package to use. Should always be the latest version, for security reasons, since this module uses very new features and to not get out of sync with the Steam API.";
     };
diff --git a/nixos/modules/services/games/terraria.nix b/nixos/modules/services/games/terraria.nix
index 571bcde2c5b2..ccdd779165b8 100644
--- a/nixos/modules/services/games/terraria.nix
+++ b/nixos/modules/services/games/terraria.nix
@@ -116,7 +116,7 @@ in
       openFirewall = mkOption {
         type = types.bool;
         default = false;
-        description = lib.mdDoc "Wheter to open ports in the firewall";
+        description = lib.mdDoc "Whether to open ports in the firewall";
       };
 
       dataDir = mkOption {
diff --git a/nixos/modules/services/hardware/argonone.nix b/nixos/modules/services/hardware/argonone.nix
index dc90e09e985b..e67c2625062e 100644
--- a/nixos/modules/services/hardware/argonone.nix
+++ b/nixos/modules/services/hardware/argonone.nix
@@ -9,7 +9,7 @@ in
     package = lib.mkOption {
       type = lib.types.package;
       default = pkgs.argononed;
-      defaultText = "pkgs.argononed";
+      defaultText = lib.literalExpression "pkgs.argononed";
       description = lib.mdDoc ''
         The package implementing the Argon One driver
       '';
diff --git a/nixos/modules/services/hardware/joycond.nix b/nixos/modules/services/hardware/joycond.nix
index f4da00762a43..1af18b3b63d3 100644
--- a/nixos/modules/services/hardware/joycond.nix
+++ b/nixos/modules/services/hardware/joycond.nix
@@ -14,7 +14,7 @@ with lib;
     package = mkOption {
       type = types.package;
       default = pkgs.joycond;
-      defaultText = "pkgs.joycond";
+      defaultText = lib.literalExpression "pkgs.joycond";
       description = lib.mdDoc ''
         The joycond package to use.
       '';
diff --git a/nixos/modules/services/matrix/conduit.nix b/nixos/modules/services/matrix/conduit.nix
index 812d463e9e86..c8d89ed33f51 100644
--- a/nixos/modules/services/matrix/conduit.nix
+++ b/nixos/modules/services/matrix/conduit.nix
@@ -23,8 +23,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.matrix-conduit;
-        defaultText = "pkgs.matrix-conduit";
-        example = "pkgs.matrix-conduit";
+        defaultText = lib.literalExpression "pkgs.matrix-conduit";
         description = lib.mdDoc ''
           Package of the conduit matrix server to use.
         '';
diff --git a/nixos/modules/services/matrix/synapse.nix b/nixos/modules/services/matrix/synapse.nix
index 86662055222a..a80d4cabfec0 100644
--- a/nixos/modules/services/matrix/synapse.nix
+++ b/nixos/modules/services/matrix/synapse.nix
@@ -286,6 +286,7 @@ in {
             log_config = mkOption {
               type = types.path;
               default = ./synapse-log_config.yaml;
+              defaultText = lib.literalExpression "nixos/modules/services/matrix/synapse-log_config.yaml";
               description = lib.mdDoc ''
                 The file that holds the logging configuration.
               '';
diff --git a/nixos/modules/services/misc/autorandr.nix b/nixos/modules/services/misc/autorandr.nix
index 365fdd5fcc39..072064143dbd 100644
--- a/nixos/modules/services/misc/autorandr.nix
+++ b/nixos/modules/services/misc/autorandr.nix
@@ -258,7 +258,7 @@ in {
         type = hooksModule;
         description = lib.mdDoc "Global hook scripts";
         default = { };
-        example = ''
+        example = literalExpression ''
           {
             postswitch = {
               "notify-i3" = "''${pkgs.i3}/bin/i3-msg restart";
@@ -279,7 +279,7 @@ in {
                     exit 1
                 esac
                 echo "Xft.dpi: $DPI" | ''${pkgs.xorg.xrdb}/bin/xrdb -merge
-              '''
+              ''';
             };
           }
         '';
diff --git a/nixos/modules/services/misc/heisenbridge.nix b/nixos/modules/services/misc/heisenbridge.nix
index 13ba362b33db..d07e0e420462 100644
--- a/nixos/modules/services/misc/heisenbridge.nix
+++ b/nixos/modules/services/misc/heisenbridge.nix
@@ -28,8 +28,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.heisenbridge;
-      defaultText = "pkgs.heisenbridge";
-      example = "pkgs.heisenbridge.override { … = …; }";
+      defaultText = lib.literalExpression "pkgs.heisenbridge";
       description = lib.mdDoc ''
         Package of the application to run, exposed for overriding purposes.
       '';
diff --git a/nixos/modules/services/misc/portunus.nix b/nixos/modules/services/misc/portunus.nix
index 0b283ea27d82..1dae605e46f2 100644
--- a/nixos/modules/services/misc/portunus.nix
+++ b/nixos/modules/services/misc/portunus.nix
@@ -29,7 +29,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.portunus;
-      defaultText = "pkgs.portunus";
+      defaultText = lib.literalExpression "pkgs.portunus";
       description = lib.mdDoc "The Portunus package to use.";
     };
 
@@ -108,7 +108,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.openldap;
-        defaultText = "pkgs.openldap";
+        defaultText = lib.literalExpression "pkgs.openldap";
         description = lib.mdDoc "The OpenLDAP package to use.";
       };
 
diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix
index aaa7bb057546..7dd254e34920 100644
--- a/nixos/modules/services/misc/sourcehut/default.nix
+++ b/nixos/modules/services/misc/sourcehut/default.nix
@@ -505,7 +505,7 @@ in
             description = lib.mdDoc "Origin URL for API, 100 more than web.";
             type = types.str;
             default = "http://${cfg.listenAddress}:${toString (cfg.meta.port + 100)}";
-            defaultText = ''http://<xref linkend="opt-services.sourcehut.listenAddress"/>:''${toString (<xref linkend="opt-services.sourcehut.meta.port"/> + 100)}'';
+            defaultText = lib.literalMD ''`"http://''${`[](#opt-services.sourcehut.listenAddress)`}:''${toString (`[](#opt-services.sourcehut.meta.port)` + 100)}"`'';
           };
           webhooks = mkOption {
             description = lib.mdDoc "The Redis connection used for the webhooks worker.";
diff --git a/nixos/modules/services/monitoring/grafana-agent.nix b/nixos/modules/services/monitoring/grafana-agent.nix
index ecb39a924f58..270d888afb78 100644
--- a/nixos/modules/services/monitoring/grafana-agent.nix
+++ b/nixos/modules/services/monitoring/grafana-agent.nix
@@ -16,7 +16,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.grafana-agent;
-      defaultText = "pkgs.grafana-agent";
+      defaultText = lib.literalExpression "pkgs.grafana-agent";
       description = lib.mdDoc "The grafana-agent package to use.";
     };
 
@@ -49,17 +49,19 @@ in
       };
 
       default = { };
-      defaultText = ''
-        metrics = {
-          wal_directory = "\''${STATE_DIRECTORY}";
-          global.scrape_interval = "5s";
-        };
-        integrations = {
-          agent.enabled = true;
-          agent.scrape_integration = true;
-          node_exporter.enabled = true;
-          replace_instance_label = true;
-        };
+      defaultText = lib.literalExpression ''
+        {
+          metrics = {
+            wal_directory = "\''${STATE_DIRECTORY}";
+            global.scrape_interval = "5s";
+          };
+          integrations = {
+            agent.enabled = true;
+            agent.scrape_integration = true;
+            node_exporter.enabled = true;
+            replace_instance_label = true;
+          };
+        }
       '';
       example = {
         metrics.global.remote_write = [{
diff --git a/nixos/modules/services/monitoring/uptime-kuma.nix b/nixos/modules/services/monitoring/uptime-kuma.nix
index 3a6091de679d..b6dc993e6a05 100644
--- a/nixos/modules/services/monitoring/uptime-kuma.nix
+++ b/nixos/modules/services/monitoring/uptime-kuma.nix
@@ -13,9 +13,8 @@ in
 
       package = mkOption {
         type = types.package;
-        example = literalExpression "pkgs.uptime-kuma";
         default = pkgs.uptime-kuma;
-        defaultText = "pkgs.uptime-kuma";
+        defaultText = literalExpression "pkgs.uptime-kuma";
         description = lib.mdDoc "Uptime Kuma package to use.";
       };
 
diff --git a/nixos/modules/services/networking/ddclient.nix b/nixos/modules/services/networking/ddclient.nix
index 5c32817979af..4d843641f58a 100644
--- a/nixos/modules/services/networking/ddclient.nix
+++ b/nixos/modules/services/networking/ddclient.nix
@@ -71,7 +71,7 @@ with lib;
       package = mkOption {
         type = package;
         default = pkgs.ddclient;
-        defaultText = "pkgs.ddclient";
+        defaultText = lib.literalExpression "pkgs.ddclient";
         description = lib.mdDoc ''
           The ddclient executable package run by the service.
         '';
diff --git a/nixos/modules/services/networking/ergochat.nix b/nixos/modules/services/networking/ergochat.nix
index 1a70b1f8613e..a003512677eb 100644
--- a/nixos/modules/services/networking/ergochat.nix
+++ b/nixos/modules/services/networking/ergochat.nix
@@ -17,10 +17,10 @@ in {
       configFile = lib.mkOption {
         type = lib.types.path;
         default = (pkgs.formats.yaml {}).generate "ergo.conf" cfg.settings;
-        defaultText = "generated config file from <literal>.settings</literal>";
+        defaultText = lib.literalMD "generated config file from `settings`";
         description = lib.mdDoc ''
           Path to configuration file.
-          Setting this will skip any configuration done via `.settings`
+          Setting this will skip any configuration done via `settings`
         '';
       };
 
diff --git a/nixos/modules/services/networking/multipath.nix b/nixos/modules/services/networking/multipath.nix
index cb6b6db272c2..54ee2a015687 100644
--- a/nixos/modules/services/networking/multipath.nix
+++ b/nixos/modules/services/networking/multipath.nix
@@ -28,7 +28,7 @@ in {
       type = package;
       description = lib.mdDoc "multipath-tools package to use";
       default = pkgs.multipath-tools;
-      defaultText = "pkgs.multipath-tools";
+      defaultText = lib.literalExpression "pkgs.multipath-tools";
     };
 
     devices = mkOption {
diff --git a/nixos/modules/services/networking/nomad.nix b/nixos/modules/services/networking/nomad.nix
index 5e5d9469efc7..890ee0b7d8d1 100644
--- a/nixos/modules/services/networking/nomad.nix
+++ b/nixos/modules/services/networking/nomad.nix
@@ -67,7 +67,7 @@ in
           Additional plugins dir used to configure nomad.
         '';
         example = literalExpression ''
-          [ "<pluginDir>" "pkgs.<plugins-name>"]
+          [ "<pluginDir>" pkgs.<plugins-name> ]
         '';
       };
 
diff --git a/nixos/modules/services/networking/sabnzbd.nix b/nixos/modules/services/networking/sabnzbd.nix
index 8486be1bc66c..8f3545df8995 100644
--- a/nixos/modules/services/networking/sabnzbd.nix
+++ b/nixos/modules/services/networking/sabnzbd.nix
@@ -20,7 +20,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.sabnzbd;
-        defaultText = "pkgs.sabnzbd";
+        defaultText = lib.literalExpression "pkgs.sabnzbd";
         description = lib.mdDoc "The sabnzbd executable package run by the service.";
       };
 
diff --git a/nixos/modules/services/search/meilisearch.nix b/nixos/modules/services/search/meilisearch.nix
index 9262b927cba4..3983b1b2c92c 100644
--- a/nixos/modules/services/search/meilisearch.nix
+++ b/nixos/modules/services/search/meilisearch.nix
@@ -21,7 +21,7 @@ in
     package = mkOption {
       description = lib.mdDoc "The package to use for meilisearch. Use this if you require specific features to be enabled. The default package has no features.";
       default = pkgs.meilisearch;
-      defaultText = "pkgs.meilisearch";
+      defaultText = lib.literalExpression "pkgs.meilisearch";
       type = types.package;
     };
 
diff --git a/nixos/modules/services/security/opensnitch.nix b/nixos/modules/services/security/opensnitch.nix
index 8f1407b555fb..98695b1ef060 100644
--- a/nixos/modules/services/security/opensnitch.nix
+++ b/nixos/modules/services/security/opensnitch.nix
@@ -91,7 +91,7 @@ in {
             InterceptUnknown = mkOption {
               type = types.bool;
               description = mdDoc ''
-                Wheter to intercept spare connections.
+                Whether to intercept spare connections.
               '';
             };
 
diff --git a/nixos/modules/services/web-apps/code-server.nix b/nixos/modules/services/web-apps/code-server.nix
index 0d6b6c529b6d..24e34e0c5833 100644
--- a/nixos/modules/services/web-apps/code-server.nix
+++ b/nixos/modules/services/web-apps/code-server.nix
@@ -15,7 +15,7 @@ in {
 
       package = mkOption {
         default = pkgs.code-server;
-        defaultText = "pkgs.code-server";
+        defaultText = lib.literalExpression "pkgs.code-server";
         description = lib.mdDoc "Which code-server derivation to use.";
         type = types.package;
       };
diff --git a/nixos/modules/services/web-apps/invidious.nix b/nixos/modules/services/web-apps/invidious.nix
index e106478628f5..a153aa3fb0c3 100644
--- a/nixos/modules/services/web-apps/invidious.nix
+++ b/nixos/modules/services/web-apps/invidious.nix
@@ -151,7 +151,7 @@ in
     package = lib.mkOption {
       type = types.package;
       default = pkgs.invidious;
-      defaultText = "pkgs.invidious";
+      defaultText = lib.literalExpression "pkgs.invidious";
       description = lib.mdDoc "The Invidious package to use.";
     };
 
diff --git a/nixos/modules/services/web-apps/mattermost.nix b/nixos/modules/services/web-apps/mattermost.nix
index 71292c47d63a..99042821f5eb 100644
--- a/nixos/modules/services/web-apps/mattermost.nix
+++ b/nixos/modules/services/web-apps/mattermost.nix
@@ -106,7 +106,7 @@ in
       package = mkOption {
         type = types.package;
         default = pkgs.mattermost;
-        defaultText = "pkgs.mattermost";
+        defaultText = lib.literalExpression "pkgs.mattermost";
         description = lib.mdDoc "Mattermost derivation to use.";
       };
 
@@ -238,7 +238,7 @@ in
         package = mkOption {
           type = types.package;
           default = pkgs.matterircd;
-          defaultText = "pkgs.matterircd";
+          defaultText = lib.literalExpression "pkgs.matterircd";
           description = lib.mdDoc "matterircd derivation to use.";
         };
         parameters = mkOption {
diff --git a/nixos/modules/services/web-apps/onlyoffice.nix b/nixos/modules/services/web-apps/onlyoffice.nix
index db4a9582794e..1478e8da87a1 100644
--- a/nixos/modules/services/web-apps/onlyoffice.nix
+++ b/nixos/modules/services/web-apps/onlyoffice.nix
@@ -29,7 +29,7 @@ in
     package = mkOption {
       type = types.package;
       default = pkgs.onlyoffice-documentserver;
-      defaultText = "pkgs.onlyoffice-documentserver";
+      defaultText = lib.literalExpression "pkgs.onlyoffice-documentserver";
       description = lib.mdDoc "Which package to use for the OnlyOffice instance.";
     };
 
diff --git a/nixos/modules/services/web-servers/lighttpd/default.nix b/nixos/modules/services/web-servers/lighttpd/default.nix
index ec847495d741..811afe8e0af6 100644
--- a/nixos/modules/services/web-servers/lighttpd/default.nix
+++ b/nixos/modules/services/web-servers/lighttpd/default.nix
@@ -137,7 +137,7 @@ in
 
       package = mkOption {
         default = pkgs.lighttpd;
-        defaultText = "pkgs.lighttpd";
+        defaultText = lib.literalExpression "pkgs.lighttpd";
         type = types.package;
         description = lib.mdDoc ''
           lighttpd package to use.
diff --git a/nixos/modules/virtualisation/qemu-vm.nix b/nixos/modules/virtualisation/qemu-vm.nix
index eae898a08a69..1b3c0e23f97d 100644
--- a/nixos/modules/virtualisation/qemu-vm.nix
+++ b/nixos/modules/virtualisation/qemu-vm.nix
@@ -580,7 +580,7 @@ in
     virtualisation.host.pkgs = mkOption {
       type = options.nixpkgs.pkgs.type;
       default = pkgs;
-      defaultText = "pkgs";
+      defaultText = literalExpression "pkgs";
       example = literalExpression ''
         import pkgs.path { system = "x86_64-darwin"; }
       '';
@@ -595,7 +595,8 @@ in
         mkOption {
           type = types.package;
           default = cfg.host.pkgs.qemu_kvm;
-          example = "pkgs.qemu_test";
+          defaultText = literalExpression "config.virtualisation.host.pkgs.qemu_kvm";
+          example = literalExpression "pkgs.qemu_test";
           description = lib.mdDoc "QEMU package to use.";
         };
 
@@ -721,7 +722,7 @@ in
       firmware = mkOption {
         type = types.path;
         default = pkgs.OVMF.firmware;
-        defaultText = "pkgs.OVMF.firmware";
+        defaultText = literalExpression "pkgs.OVMF.firmware";
         description =
           lib.mdDoc ''
             Firmware binary for EFI implementation, defaults to OVMF.
@@ -731,7 +732,7 @@ in
       variables = mkOption {
         type = types.path;
         default = pkgs.OVMF.variables;
-        defaultText = "pkgs.OVMF.variables";
+        defaultText = literalExpression "pkgs.OVMF.variables";
         description =
           lib.mdDoc ''
             Platform-specific flash binary for EFI variables, implementation-dependent to the EFI firmware.