diff options
| author | pennae <github@quasiparticle.net> | 2022-08-05 19:39:00 +0200 |
|---|---|---|
| committer | pennae <github@quasiparticle.net> | 2022-08-06 20:39:12 +0200 |
| commit | 087472b1e5230ffc8ba642b1e4f9218adf4634a2 (patch) | |
| tree | ba5c8e457072dce9aa13a92f26bb7e6a47d45776 | |
| parent | 423545fe4865d126e86721ba30da116e29c65004 (diff) | |
| download | nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.tar nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.tar.gz nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.tar.bz2 nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.tar.lz nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.tar.xz nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.tar.zst nixpkgs-087472b1e5230ffc8ba642b1e4f9218adf4634a2.zip | |
nixos/*: automatically convert option docs
162 files changed, 1552 insertions, 1552 deletions
diff --git a/nixos/modules/config/sysctl.nix b/nixos/modules/config/sysctl.nix index a691923e1ab..b4b2d0452c4 100644 --- a/nixos/modules/config/sysctl.nix +++ b/nixos/modules/config/sysctl.nix @@ -26,12 +26,12 @@ in { "net.ipv4.tcp_syncookies" = false; "vm.swappiness" = 60; } ''; type = types.attrsOf sysctlOption; - description = '' + description = lib.mdDoc '' Runtime parameters of the Linux kernel, as set by - <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Note that sysctl + {manpage}`sysctl(8)`. Note that sysctl parameters names must be enclosed in quotes - (e.g. <literal>"vm.swappiness"</literal> instead of - <literal>vm.swappiness</literal>). The value of each + (e.g. `"vm.swappiness"` instead of + `vm.swappiness`). The value of each parameter may be a string, integer, boolean, or null (signifying the option will not appear at all). ''; diff --git a/nixos/modules/config/system-environment.nix b/nixos/modules/config/system-environment.nix index 5d7184d0485..5b226d5079b 100644 --- a/nixos/modules/config/system-environment.nix +++ b/nixos/modules/config/system-environment.nix @@ -39,23 +39,23 @@ in environment.profileRelativeSessionVariables = mkOption { type = types.attrsOf (types.listOf types.str); example = { PATH = [ "/bin" ]; MANPATH = [ "/man" "/share/man" ]; }; - description = '' + description = lib.mdDoc '' Attribute set of environment variable used in the global environment. These variables will be set by PAM early in the login process. Variable substitution is available as described in - <citerefentry><refentrytitle>pam_env.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`pam_env.conf(5)`. Each attribute maps to a list of relative paths. Each relative path is appended to the each profile of - <option>environment.profiles</option> to form the content of + {option}`environment.profiles` to form the content of the corresponding environment variable. Also, these variables are merged into - <xref linkend="opt-environment.profileRelativeEnvVars"/> and it is + [](#opt-environment.profileRelativeEnvVars) and it is therefore not possible to use PAM style variables such as - <literal>@{HOME}</literal>. + `@{HOME}`. ''; }; diff --git a/nixos/modules/installer/cd-dvd/iso-image.nix b/nixos/modules/installer/cd-dvd/iso-image.nix index cefe252e2e9..6d0a11b7491 100644 --- a/nixos/modules/installer/cd-dvd/iso-image.nix +++ b/nixos/modules/installer/cd-dvd/iso-image.nix @@ -454,23 +454,23 @@ in isoImage.isoName = mkOption { default = "${config.isoImage.isoBaseName}.iso"; - description = '' + description = lib.mdDoc '' Name of the generated ISO image file. ''; }; isoImage.isoBaseName = mkOption { default = "nixos"; - description = '' + description = lib.mdDoc '' Prefix of the name of the generated ISO image file. ''; }; isoImage.compressImage = mkOption { default = false; - description = '' + description = lib.mdDoc '' Whether the ISO image should be compressed using - <command>zstd</command>. + {command}`zstd`. ''; }; @@ -481,7 +481,7 @@ in + lib.optionalString isAarch "-Xbcj arm" + lib.optionalString (isPower && is32bit && isBigEndian) "-Xbcj powerpc" + lib.optionalString (isSparc) "-Xbcj sparc"; - description = '' + description = lib.mdDoc '' Compression settings to use for the squashfs nix store. ''; example = "zstd -Xcompression-level 6"; @@ -489,7 +489,7 @@ in isoImage.edition = mkOption { default = ""; - description = '' + description = lib.mdDoc '' Specifies which edition string to use in the volume ID of the generated ISO image. ''; @@ -498,7 +498,7 @@ in isoImage.volumeID = mkOption { # nixos-$EDITION-$RELEASE-$ARCH default = "nixos${optionalString (config.isoImage.edition != "") "-${config.isoImage.edition}"}-${config.system.nixos.release}-${pkgs.stdenv.hostPlatform.uname.processor}"; - description = '' + description = lib.mdDoc '' Specifies the label or volume ID of the generated ISO image. Note that the label is used by stage 1 of the boot process to mount the CD, so it should be reasonably distinctive. @@ -512,7 +512,7 @@ in } ] ''; - description = '' + description = lib.mdDoc '' This option lists files to be copied to fixed locations in the generated ISO image. ''; @@ -520,7 +520,7 @@ in isoImage.storeContents = mkOption { example = literalExpression "[ pkgs.stdenv ]"; - description = '' + description = lib.mdDoc '' This option lists additional derivations to be included in the Nix store in the generated ISO image. ''; @@ -528,7 +528,7 @@ in isoImage.includeSystemBuildDependencies = mkOption { default = false; - description = '' + description = lib.mdDoc '' Set this option to include all the needed sources etc in the image. It significantly increases image size. Use that when you want to be able to keep all the sources needed to build your @@ -539,14 +539,14 @@ in isoImage.makeEfiBootable = mkOption { default = false; - description = '' + description = lib.mdDoc '' Whether the ISO image should be an efi-bootable volume. ''; }; isoImage.makeUsbBootable = mkOption { default = false; - description = '' + description = lib.mdDoc '' Whether the ISO image should be bootable from CD as well as USB. ''; }; @@ -556,7 +556,7 @@ in url = "https://raw.githubusercontent.com/NixOS/nixos-artwork/a9e05d7deb38a8e005a2b52575a3f59a63a4dba0/bootloader/efi-background.png"; sha256 = "18lfwmp8yq923322nlb9gxrh5qikj1wsk6g5qvdh31c4h5b1538x"; }; - description = '' + description = lib.mdDoc '' The splash image to use in the EFI bootloader. ''; }; @@ -566,7 +566,7 @@ in url = "https://raw.githubusercontent.com/NixOS/nixos-artwork/a9e05d7deb38a8e005a2b52575a3f59a63a4dba0/bootloader/isolinux/bios-boot.png"; sha256 = "1wp822zrhbg4fgfbwkr7cbkr4labx477209agzc0hr6k62fr6rxd"; }; - description = '' + description = lib.mdDoc '' The splash image to use in the legacy-boot bootloader. ''; }; @@ -574,7 +574,7 @@ in isoImage.grubTheme = mkOption { default = pkgs.nixos-grub2-theme; type = types.nullOr (types.either types.path types.package); - description = '' + description = lib.mdDoc '' The grub2 theme used for UEFI boot. ''; }; @@ -605,7 +605,7 @@ in MENU COLOR SEL 7;37;40 #FFFFFFFF #FF5277C3 std ''; type = types.str; - description = '' + description = lib.mdDoc '' The syslinux theme used for BIOS boot. ''; }; @@ -613,12 +613,12 @@ in isoImage.appendToMenuLabel = mkOption { default = " Installer"; example = " Live System"; - description = '' + description = lib.mdDoc '' The string to append after the menu label for the NixOS system. This will be directly appended (without whitespace) to the NixOS version - string, like for example if it is set to <literal>XXX</literal>: + string, like for example if it is set to `XXX`: - <literal>NixOS 99.99-pre666XXX</literal> + `NixOS 99.99-pre666XXX` ''; }; diff --git a/nixos/modules/installer/netboot/netboot.nix b/nixos/modules/installer/netboot/netboot.nix index fed6a7c3728..03bb529cd85 100644 --- a/nixos/modules/installer/netboot/netboot.nix +++ b/nixos/modules/installer/netboot/netboot.nix @@ -10,7 +10,7 @@ with lib; netboot.storeContents = mkOption { example = literalExpression "[ pkgs.stdenv ]"; - description = '' + description = lib.mdDoc '' This option lists additional derivations to be included in the Nix store in the generated netboot image. ''; diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index fbde1dea037..b67089a3d59 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -157,9 +157,9 @@ in enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to install documentation of packages from - <option>environment.systemPackages</option> into the generated system path. + {option}`environment.systemPackages` into the generated system path. See "Multiple-output packages" chapter in the nixpkgs manual for more info. ''; @@ -169,9 +169,9 @@ in man.enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to install manual pages. - This also includes <literal>man</literal> outputs. + This also includes `man` outputs. ''; }; @@ -190,8 +190,8 @@ in info.enable = mkOption { type = types.bool; default = true; - description = '' - Whether to install info pages and the <command>info</command> command. + description = lib.mdDoc '' + Whether to install info pages and the {command}`info` command. This also includes "info" outputs. ''; }; @@ -199,8 +199,8 @@ in doc.enable = mkOption { type = types.bool; default = true; - description = '' - Whether to install documentation distributed in packages' <literal>/share/doc</literal>. + description = lib.mdDoc '' + Whether to install documentation distributed in packages' `/share/doc`. Usually plain text and/or HTML. This also includes "doc" outputs. ''; @@ -238,7 +238,7 @@ in nixos.options.splitBuild = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to split the option docs build into a cacheable and an uncacheable part. Splitting the build can substantially decrease the amount of time needed to build the manual, but some user modules may be incompatible with this splitting. @@ -248,7 +248,7 @@ in nixos.options.warningsAreErrors = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Treat warning emitted during the option documentation build (eg for missing option descriptions) as errors. ''; @@ -257,18 +257,18 @@ in nixos.includeAllModules = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether the generated NixOS's documentation should include documentation for all the options from all the NixOS modules included in the current - <literal>configuration.nix</literal>. Disabling this will make the manual - generator to ignore options defined outside of <literal>baseModules</literal>. + `configuration.nix`. Disabling this will make the manual + generator to ignore options defined outside of `baseModules`. ''; }; nixos.extraModuleSources = mkOption { type = types.listOf (types.either types.path types.str); default = [ ]; - description = '' + description = lib.mdDoc '' Which extra NixOS module paths the generated NixOS's documentation should strip from options. ''; diff --git a/nixos/modules/misc/locate.nix b/nixos/modules/misc/locate.nix index cb7b5a308c5..b83e280b284 100644 --- a/nixos/modules/misc/locate.nix +++ b/nixos/modules/misc/locate.nix @@ -39,15 +39,15 @@ in type = str; default = "02:15"; example = "hourly"; - description = '' + description = lib.mdDoc '' Update the locate database at this interval. Updates by default at 2:15 AM every day. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. - To disable automatic updates, set to <literal>"never"</literal> - and run <command>updatedb</command> manually. + To disable automatic updates, set to `"never"` + and run {command}`updatedb` manually. ''; }; diff --git a/nixos/modules/misc/nixpkgs.nix b/nixos/modules/misc/nixpkgs.nix index bb21e31ec97..721a041a583 100644 --- a/nixos/modules/misc/nixpkgs.nix +++ b/nixos/modules/misc/nixpkgs.nix @@ -157,12 +157,12 @@ in { allowBroken = true; allowUnfree = true; } ''; type = configType; - description = '' + description = lib.mdDoc '' The configuration of the Nix Packages collection. (For details, see the Nixpkgs documentation.) It allows you to set package configuration options. - Ignored when <literal>nixpkgs.pkgs</literal> is set. + Ignored when `nixpkgs.pkgs` is set. ''; }; @@ -180,17 +180,17 @@ in ] ''; type = types.listOf overlayType; - description = '' + description = lib.mdDoc '' List of overlays to use with the Nix Packages collection. (For details, see the Nixpkgs documentation.) It allows you to override packages globally. Each function in the list - takes as an argument the <emphasis>original</emphasis> Nixpkgs. + takes as an argument the *original* Nixpkgs. The first argument should be used for finding dependencies, and the second should be used for overriding recipes. - If <literal>nixpkgs.pkgs</literal> is set, overlays specified here + If `nixpkgs.pkgs` is set, overlays specified here will be applied after the overlays that were already present - in <literal>nixpkgs.pkgs</literal>. + in `nixpkgs.pkgs`. ''; }; @@ -202,12 +202,12 @@ in apply = lib.systems.elaborate; defaultText = literalExpression ''(import "''${nixos}/../lib").lib.systems.examples.aarch64-multiplatform''; - description = '' + description = lib.mdDoc '' Specifies the platform where the NixOS configuration will run. - To cross-compile, set also <literal>nixpkgs.buildPlatform</literal>. + To cross-compile, set also `nixpkgs.buildPlatform`. - Ignored when <literal>nixpkgs.pkgs</literal> is set. + Ignored when `nixpkgs.pkgs` is set. ''; }; @@ -220,7 +220,7 @@ in apply = lib.systems.elaborate; defaultText = literalExpression ''config.nixpkgs.hostPlatform''; - description = '' + description = lib.mdDoc '' Specifies the platform on which NixOS should be built. By default, NixOS is built on the system where it runs, but you can change where it's built. Setting this option will cause NixOS to be @@ -230,7 +230,7 @@ in or if you're building machines, you can set this to match your development system and/or build farm. - Ignored when <literal>nixpkgs.pkgs</literal> is set. + Ignored when `nixpkgs.pkgs` is set. ''; }; @@ -243,25 +243,25 @@ in apply = lib.systems.elaborate; defaultText = literalExpression ''(import "''${nixos}/../lib").lib.systems.examples.aarch64-multiplatform''; - description = '' - Systems with a recently generated <literal>hardware-configuration.nix</literal> + description = lib.mdDoc '' + Systems with a recently generated `hardware-configuration.nix` do not need to specify this option, unless cross-compiling, in which case - you should set <emphasis>only</emphasis> <option>nixpkgs.buildPlatform</option>. + you should set *only* {option}`nixpkgs.buildPlatform`. If this is somehow not feasible, you may fall back to removing the - <option>nixpkgs.hostPlatform</option> line from the generated config and + {option}`nixpkgs.hostPlatform` line from the generated config and use the old options. Specifies the platform on which NixOS should be built. When - <literal>nixpkgs.crossSystem</literal> is unset, it also specifies - the platform <emphasis>for</emphasis> which NixOS should be + `nixpkgs.crossSystem` is unset, it also specifies + the platform *for* which NixOS should be built. If this option is unset, it defaults to the platform type of the machine where evaluation happens. Specifying this option is useful when doing distributed multi-platform deployment, or when building virtual machines. See its description in the Nixpkgs manual for more details. - Ignored when <literal>nixpkgs.pkgs</literal> or <literal>hostPlatform</literal> is set. + Ignored when `nixpkgs.pkgs` or `hostPlatform` is set. ''; }; @@ -272,20 +272,20 @@ in type = types.nullOr types.attrs; # TODO utilize lib.systems.parsedPlatform default = null; example = { system = "aarch64-linux"; config = "aarch64-unknown-linux-gnu"; }; - description = '' - Systems with a recently generated <literal>hardware-configuration.nix</literal> - may instead specify <emphasis>only</emphasis> <option>nixpkgs.buildPlatform</option>, - or fall back to removing the <option>nixpkgs.hostPlatform</option> line from the generated config. + description = lib.mdDoc '' + Systems with a recently generated `hardware-configuration.nix` + may instead specify *only* {option}`nixpkgs.buildPlatform`, + or fall back to removing the {option}`nixpkgs.hostPlatform` line from the generated config. Specifies the platform for which NixOS should be built. Specify this only if it is different from - <literal>nixpkgs.localSystem</literal>, the platform - <emphasis>on</emphasis> which NixOS should be built. In other + `nixpkgs.localSystem`, the platform + *on* which NixOS should be built. In other words, specify this to cross-compile NixOS. Otherwise it should be set as null, the default. See its description in the Nixpkgs manual for more details. - Ignored when <literal>nixpkgs.pkgs</literal> or <literal>hostPlatform</literal> is set. + Ignored when `nixpkgs.pkgs` or `hostPlatform` is set. ''; }; diff --git a/nixos/modules/profiles/clone-config.nix b/nixos/modules/profiles/clone-config.nix index 3f669ba7d2e..ba65a250d25 100644 --- a/nixos/modules/profiles/clone-config.nix +++ b/nixos/modules/profiles/clone-config.nix @@ -61,7 +61,7 @@ in installer.cloneConfig = mkOption { default = true; - description = '' + description = lib.mdDoc '' Try to clone the installation-device configuration by re-using it's profile from the list of imported modules. ''; @@ -70,14 +70,14 @@ in installer.cloneConfigIncludes = mkOption { default = []; example = [ "./nixos/modules/hardware/network/rt73.nix" ]; - description = '' + description = lib.mdDoc '' List of modules used to re-build this installation device profile. ''; }; installer.cloneConfigExtra = mkOption { default = ""; - description = '' + description = lib.mdDoc '' Extra text to include in the cloned configuration.nix included in this installer. ''; diff --git a/nixos/modules/security/acme/default.nix b/nixos/modules/security/acme/default.nix index f4f2a669ceb..1df6d9eba95 100644 --- a/nixos/modules/security/acme/default.nix +++ b/nixos/modules/security/acme/default.nix @@ -451,9 +451,9 @@ let renewInterval = mkOption { type = types.str; inherit (defaultAndText "renewInterval" "daily") default defaultText; - description = '' + description = lib.mdDoc '' Systemd calendar expression when to check for renewal. See - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/security/apparmor.nix b/nixos/modules/security/apparmor.nix index be1b0362fc1..c4eca453254 100644 --- a/nixos/modules/security/apparmor.nix +++ b/nixos/modules/security/apparmor.nix @@ -42,7 +42,7 @@ in if you want this service to do such killing by sending a <literal>SIGTERM</literal> to those running processes''; policies = mkOption { - description = '' + description = lib.mdDoc '' AppArmor policies. ''; type = types.attrsOf (types.submodule ({ name, config, ... }: { @@ -50,7 +50,7 @@ in enable = mkDisableOption "loading of the profile into the kernel"; enforce = mkDisableOption "enforcing of the policy or only complain in the logs"; profile = mkOption { - description = "The policy of the profile."; + description = lib.mdDoc "The policy of the profile."; type = types.lines; apply = pkgs.writeText name; }; @@ -61,16 +61,16 @@ in includes = mkOption { type = types.attrsOf types.lines; default = {}; - description = '' + description = lib.mdDoc '' List of paths to be added to AppArmor's searched paths - when resolving <literal>include</literal> directives. + when resolving `include` directives. ''; apply = mapAttrs pkgs.writeText; }; packages = mkOption { type = types.listOf types.package; default = []; - description = "List of packages to be added to AppArmor's include path"; + description = lib.mdDoc "List of packages to be added to AppArmor's include path"; }; enableCache = mkEnableOption '' caching of AppArmor policies diff --git a/nixos/modules/security/pam.nix b/nixos/modules/security/pam.nix index 86fa5db6ca5..9a1acba00d0 100644 --- a/nixos/modules/security/pam.nix +++ b/nixos/modules/security/pam.nix @@ -836,14 +836,14 @@ in control = mkOption { default = "sufficient"; type = types.enum [ "required" "requisite" "sufficient" "optional" ]; - description = '' + description = lib.mdDoc '' This option sets pam "control". If you want to have multi factor authentication, use "required". If you want to use the PKCS#11 device instead of the regular password, use "sufficient". Read - <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`pam.conf(5)` for better understanding of this option. ''; }; @@ -924,13 +924,13 @@ in control = mkOption { default = "sufficient"; type = types.enum [ "required" "requisite" "sufficient" "optional" ]; - description = '' + description = lib.mdDoc '' This option sets pam "control". If you want to have multi factor authentication, use "required". If you want to use U2F device instead of regular password, use "sufficient". Read - <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`pam.conf(5)` for better understanding of this option. ''; }; @@ -1039,14 +1039,14 @@ in control = mkOption { default = "sufficient"; type = types.enum [ "required" "requisite" "sufficient" "optional" ]; - description = '' + description = lib.mdDoc '' This option sets pam "control". If you want to have multi factor authentication, use "required". If you want to use the SSH certificate instead of the regular password, use "sufficient". Read - <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`pam.conf(5)` for better understanding of this option. ''; }; @@ -1071,13 +1071,13 @@ in control = mkOption { default = "sufficient"; type = types.enum [ "required" "requisite" "sufficient" "optional" ]; - description = '' + description = lib.mdDoc '' This option sets pam "control". If you want to have multi factor authentication, use "required". If you want to use Yubikey instead of regular password, use "sufficient". Read - <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`pam.conf(5)` for better understanding of this option. ''; }; diff --git a/nixos/modules/security/systemd-confinement.nix b/nixos/modules/security/systemd-confinement.nix index b058eed42c4..f5ed3d281a5 100644 --- a/nixos/modules/security/systemd-confinement.nix +++ b/nixos/modules/security/systemd-confinement.nix @@ -10,10 +10,10 @@ in { options.confinement.enable = lib.mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If set, all the required runtime store paths for this service are - bind-mounted into a <literal>tmpfs</literal>-based - <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + bind-mounted into a `tmpfs`-based + {manpage}`chroot(2)`. ''; }; @@ -61,13 +61,13 @@ in { default = toplevelConfig.environment.binsh; defaultText = lib.literalExpression "config.environment.binsh"; example = lib.literalExpression ''"''${pkgs.dash}/bin/dash"''; - description = '' - The program to make available as <filename>/bin/sh</filename> inside - the chroot. If this is set to <literal>null</literal>, no - <filename>/bin/sh</filename> is provided at all. + description = lib.mdDoc '' + The program to make available as {file}`/bin/sh` inside + the chroot. If this is set to `null`, no + {file}`/bin/sh` is provided at all. This is useful for some applications, which for example use the - <citerefentry><refentrytitle>system</refentrytitle><manvolnum>3</manvolnum></citerefentry> library function to execute commands. + {manpage}`system(3)` library function to execute commands. ''; }; diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix index bd006fdf77f..3abd33f5ae6 100644 --- a/nixos/modules/services/backup/borgbackup.nix +++ b/nixos/modules/services/backup/borgbackup.nix @@ -320,12 +320,12 @@ in { startAt = mkOption { type = with types; either str (listOf str); default = "daily"; - description = '' + description = lib.mdDoc '' When or how often the backup should run. Must be in the format described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. If you do not want the backup to start - automatically, use <literal>[ ]</literal>. + automatically, use `[ ]`. It will generate a systemd service borgbackup-job-NAME. You may trigger it manually via systemctl restart borgbackup-job-NAME. ''; @@ -335,9 +335,9 @@ in { default = false; type = types.bool; example = true; - description = '' - Set the <literal>persistentTimer</literal> option for the - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + description = lib.mdDoc '' + Set the `persistentTimer` option for the + {manpage}`systemd.timer(5)` which triggers the backup immediately if the last trigger was missed (e.g. if the system was powered down). ''; diff --git a/nixos/modules/services/backup/duplicity.nix b/nixos/modules/services/backup/duplicity.nix index cd9b78f440a..afa4f31b129 100644 --- a/nixos/modules/services/backup/duplicity.nix +++ b/nixos/modules/services/backup/duplicity.nix @@ -27,27 +27,27 @@ in type = types.listOf types.str; default = [ ]; example = [ "/home" ]; - description = '' + description = lib.mdDoc '' List of paths to include into the backups. See the FILE SELECTION - section in <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details on the syntax. + section in {manpage}`duplicity(1)` for details on the syntax. ''; }; exclude = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' List of paths to exclude from backups. See the FILE SELECTION section in - <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details on the syntax. + {manpage}`duplicity(1)` for details on the syntax. ''; }; targetUrl = mkOption { type = types.str; example = "s3://host:port/prefix"; - description = '' + description = lib.mdDoc '' Target url to backup to. See the URL FORMAT section in - <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry> for supported urls. + {manpage}`duplicity(1)` for supported urls. ''; }; @@ -69,9 +69,9 @@ in frequency = mkOption { type = types.nullOr types.str; default = "daily"; - description = '' + description = lib.mdDoc '' Run duplicity with the given frequency (see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for the format). + {manpage}`systemd.time(7)` for the format). If null, do not run automatically. ''; }; @@ -80,9 +80,9 @@ in type = types.listOf types.str; default = [ ]; example = [ "--backend-retry-delay" "100" ]; - description = '' + description = lib.mdDoc '' Extra command-line flags passed to duplicity. See - <citerefentry><refentrytitle>duplicity</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + {manpage}`duplicity(1)`. ''; }; diff --git a/nixos/modules/services/backup/sanoid.nix b/nixos/modules/services/backup/sanoid.nix index 2b988518d59..0c01aa57f7e 100644 --- a/nixos/modules/services/backup/sanoid.nix +++ b/nixos/modules/services/backup/sanoid.nix @@ -118,11 +118,11 @@ in type = types.str; default = "hourly"; example = "daily"; - description = '' + description = lib.mdDoc '' Run sanoid at this interval. The default is to run hourly. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/backup/syncoid.nix b/nixos/modules/services/backup/syncoid.nix index 46e52632819..779c71a6ba9 100644 --- a/nixos/modules/services/backup/syncoid.nix +++ b/nixos/modules/services/backup/syncoid.nix @@ -89,11 +89,11 @@ in type = types.str; default = "hourly"; example = "*-*-* *:15:00"; - description = '' + description = lib.mdDoc '' Run syncoid at this interval. The default is to run hourly. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/backup/tarsnap.nix b/nixos/modules/services/backup/tarsnap.nix index ec810c46674..c2d4f87362e 100644 --- a/nixos/modules/services/backup/tarsnap.nix +++ b/nixos/modules/services/backup/tarsnap.nix @@ -140,11 +140,11 @@ in type = types.str; default = "01:15"; example = "hourly"; - description = '' + description = lib.mdDoc '' Create archive at this interval. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/cluster/hadoop/default.nix b/nixos/modules/services/cluster/hadoop/default.nix index a4fdea81037..af35492484e 100644 --- a/nixos/modules/services/cluster/hadoop/default.nix +++ b/nixos/modules/services/cluster/hadoop/default.nix @@ -16,9 +16,9 @@ with lib; "fs.defaultFS" = "hdfs://localhost"; } ''; - description = '' + description = lib.mdDoc '' Hadoop core-site.xml definition - <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/core-default.xml"/> + <https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/core-default.xml> ''; }; coreSiteInternal = mkOption { @@ -38,7 +38,7 @@ with lib; "dfs.namenode.http-bind-host" = "0.0.0.0"; }; type = types.attrsOf types.anything; - description = '' + description = lib.mdDoc '' Default options for hdfs-site.xml ''; }; @@ -50,9 +50,9 @@ with lib; "dfs.nameservices" = "namenode1"; } ''; - description = '' + description = lib.mdDoc '' Additional options and overrides for hdfs-site.xml - <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/hdfs-default.xml"/> + <https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/hdfs-default.xml> ''; }; hdfsSiteInternal = mkOption { @@ -80,7 +80,7 @@ with lib; } ''; type = types.attrsOf types.anything; - description = '' + description = lib.mdDoc '' Default options for mapred-site.xml ''; }; @@ -92,9 +92,9 @@ with lib; "mapreduce.map.java.opts" = "-Xmx900m -XX:+UseParallelGC"; } ''; - description = '' + description = lib.mdDoc '' Additional options and overrides for mapred-site.xml - <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-mapreduce-client/hadoop-mapreduce-client-core/mapred-default.xml"/> + <https://hadoop.apache.org/docs/current/hadoop-mapreduce-client/hadoop-mapreduce-client-core/mapred-default.xml> ''; }; @@ -113,7 +113,7 @@ with lib; "yarn.resourcemanager.scheduler.class" = "org.apache.hadoop.yarn.server.resourcemanager.scheduler.fair.FairScheduler"; }; type = types.attrsOf types.anything; - description = '' + description = lib.mdDoc '' Default options for yarn-site.xml ''; }; @@ -125,9 +125,9 @@ with lib; "yarn.resourcemanager.hostname" = "''${config.networking.hostName}"; } ''; - description = '' + description = lib.mdDoc '' Additional options and overrides for yarn-site.xml - <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-common/yarn-default.xml"/> + <https://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-common/yarn-default.xml> ''; }; yarnSiteInternal = mkOption { @@ -147,9 +147,9 @@ with lib; "hadoop.http.max.threads" = 500; } ''; - description = '' + description = lib.mdDoc '' Hadoop httpfs-site.xml definition - <link xlink:href="https://hadoop.apache.org/docs/current/hadoop-hdfs-httpfs/httpfs-default.html"/> + <https://hadoop.apache.org/docs/current/hadoop-hdfs-httpfs/httpfs-default.html> ''; }; @@ -162,7 +162,7 @@ with lib; example = literalExpression '' "''${pkgs.hadoop}/lib/''${pkgs.hadoop.untarDir}/etc/hadoop/log4j.properties"; ''; - description = "log4j.properties file added to HADOOP_CONF_DIR"; + description = lib.mdDoc "log4j.properties file added to HADOOP_CONF_DIR"; }; containerExecutorCfg = mkOption { @@ -179,9 +179,9 @@ with lib; "feature.terminal.enabled" = 0; } ''; - description = '' + description = lib.mdDoc '' Yarn container-executor.cfg definition - <link xlink:href="https://hadoop.apache.org/docs/r2.7.2/hadoop-yarn/hadoop-yarn-site/SecureContainer.html"/> + <https://hadoop.apache.org/docs/r2.7.2/hadoop-yarn/hadoop-yarn-site/SecureContainer.html> ''; }; @@ -194,7 +194,7 @@ with lib; ./extraYARNConfs ] ''; - description = "Directories containing additional config files to be added to HADOOP_CONF_DIR"; + description = lib.mdDoc "Directories containing additional config files to be added to HADOOP_CONF_DIR"; }; gatewayRole.enable = mkEnableOption "gateway role for deploying hadoop configs"; diff --git a/nixos/modules/services/computing/slurm/slurm.nix b/nixos/modules/services/computing/slurm/slurm.nix index 88c65a3fbbe..0860b9a220c 100644 --- a/nixos/modules/services/computing/slurm/slurm.nix +++ b/nixos/modules/services/computing/slurm/slurm.nix @@ -109,9 +109,9 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra configuration for <literal>slurmdbd.conf</literal> See also: - <citerefentry><refentrytitle>slurmdbd.conf</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + description = lib.mdDoc '' + Extra configuration for `slurmdbd.conf` See also: + {manpage}`slurmdbd.conf(8)`. ''; }; }; diff --git a/nixos/modules/services/databases/rethinkdb.nix b/nixos/modules/services/databases/rethinkdb.nix index c764d6c21c6..d93f15e8636 100644 --- a/nixos/modules/services/databases/rethinkdb.nix +++ b/nixos/modules/services/databases/rethinkdb.nix @@ -24,22 +24,22 @@ in user = mkOption { default = "rethinkdb"; - description = "User account under which RethinkDB runs."; + description = lib.mdDoc "User account under which RethinkDB runs."; }; group = mkOption { default = "rethinkdb"; - description = "Group which rethinkdb user belongs to."; + description = lib.mdDoc "Group which rethinkdb user belongs to."; }; dbpath = mkOption { default = "/var/db/rethinkdb"; - description = "Location where RethinkDB stores its data, 1 data directory per instance."; + description = lib.mdDoc "Location where RethinkDB stores its data, 1 data directory per instance."; }; pidpath = mkOption { default = "/run/rethinkdb"; - description = "Location where each instance's pid file is located."; + description = lib.mdDoc "Location where each instance's pid file is located."; }; #cfgpath = mkOption { diff --git a/nixos/modules/services/desktops/pipewire/pipewire-media-session.nix b/nixos/modules/services/desktops/pipewire/pipewire-media-session.nix index 09761d6300e..203139294c6 100644 --- a/nixos/modules/services/desktops/pipewire/pipewire-media-session.nix +++ b/nixos/modules/services/desktops/pipewire/pipewire-media-session.nix @@ -39,14 +39,14 @@ in { enable = mkOption { type = types.bool; default = false; - description = "Whether to enable the deprecated example Pipewire session manager"; + description = lib.mdDoc "Whether to enable the deprecated example Pipewire session manager"; }; package = mkOption { type = types.package; default = pkgs.pipewire-media-session; defaultText = literalExpression "pkgs.pipewire-media-session"; - description = '' + description = lib.mdDoc '' The pipewire-media-session derivation to use. ''; }; @@ -54,7 +54,7 @@ in { config = { media-session = mkOption { type = json.type; - description = '' + description = lib.mdDoc '' Configuration for the media session core. For details see https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/media-session.conf ''; @@ -63,7 +63,7 @@ in { alsa-monitor = mkOption { type = json.type; - description = '' + description = lib.mdDoc '' Configuration for the alsa monitor. For details see https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/alsa-monitor.conf ''; @@ -72,7 +72,7 @@ in { bluez-monitor = mkOption { type = json.type; - description = '' + description = lib.mdDoc '' Configuration for the bluez5 monitor. For details see https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/bluez-monitor.conf ''; @@ -81,7 +81,7 @@ in { v4l2-monitor = mkOption { type = json.type; - description = '' + description = lib.mdDoc '' Configuration for the V4L2 monitor. For details see https://gitlab.freedesktop.org/pipewire/media-session/-/blob/${cfg.package.version}/src/daemon/media-session.d/v4l2-monitor.conf ''; diff --git a/nixos/modules/services/development/jupyter/default.nix b/nixos/modules/services/development/jupyter/default.nix index 7c86e8b6478..b77f5adbd5e 100644 --- a/nixos/modules/services/development/jupyter/default.nix +++ b/nixos/modules/services/development/jupyter/default.nix @@ -29,7 +29,7 @@ in { ip = mkOption { type = types.str; default = "localhost"; - description = '' + description = lib.mdDoc '' IP address Jupyter will be listening on. ''; }; @@ -41,7 +41,7 @@ in { # saving a rebuild. default = pkgs.python3.pkgs.notebook; defaultText = literalExpression "pkgs.python3.pkgs.notebook"; - description = '' + description = lib.mdDoc '' Jupyter package to use. ''; }; @@ -50,7 +50,7 @@ in { type = types.str; default = "jupyter-notebook"; example = "jupyter-lab"; - description = '' + description = lib.mdDoc '' Which command the service runs. Note that not all jupyter packages have all commands, e.g. jupyter-lab isn't present in the default package. ''; @@ -59,7 +59,7 @@ in { port = mkOption { type = types.int; default = 8888; - description = '' + description = lib.mdDoc '' Port number Jupyter will be listening on. ''; }; @@ -67,7 +67,7 @@ in { notebookDir = mkOption { type = types.str; default = "~/"; - description = '' + description = lib.mdDoc '' Root directory for notebooks. ''; }; @@ -75,7 +75,7 @@ in { user = mkOption { type = types.str; default = "jupyter"; - description = '' + description = lib.mdDoc '' Name of the user used to run the jupyter service. For security reason, jupyter should really not be run as root. If not set (jupyter), the service will create a jupyter user with appropriate settings. @@ -86,7 +86,7 @@ in { group = mkOption { type = types.str; default = "jupyter"; - description = '' + description = lib.mdDoc '' Name of the group used to run the jupyter service. Use this if you want to create a group of users that are able to view the notebook directory's content. ''; @@ -95,7 +95,7 @@ in { password = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Password to use with notebook. Can be generated using: In [1]: from notebook.auth import passwd @@ -112,7 +112,7 @@ in { notebookConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Raw jupyter config. ''; }; diff --git a/nixos/modules/services/development/jupyter/kernel-options.nix b/nixos/modules/services/development/jupyter/kernel-options.nix index 0a9eaafa318..42af47aeb3c 100644 --- a/nixos/modules/services/development/jupyter/kernel-options.nix +++ b/nixos/modules/services/development/jupyter/kernel-options.nix @@ -13,7 +13,7 @@ with lib; "Python 3" "Python 3 for Data Science" ''; - description = '' + description = lib.mdDoc '' Name that will be shown to the user. ''; }; @@ -27,7 +27,7 @@ with lib; "-f" "{connection_file}" ]; - description = '' + description = lib.mdDoc '' Command and arguments to start the kernel. ''; }; @@ -35,7 +35,7 @@ with lib; language = mkOption { type = types.str; example = "python"; - description = '' + description = lib.mdDoc '' Language of the environment. Typically the name of the binary. ''; }; @@ -44,7 +44,7 @@ with lib; type = types.nullOr types.path; default = null; example = literalExpression ''"''${env.sitePackages}/ipykernel/resources/logo-32x32.png"''; - description = '' + description = lib.mdDoc '' Path to 32x32 logo png. ''; }; @@ -52,7 +52,7 @@ with lib; type = types.nullOr types.path; default = null; example = literalExpression ''"''${env.sitePackages}/ipykernel/resources/logo-64x64.png"''; - description = '' + description = lib.mdDoc '' Path to 64x64 logo png. ''; }; @@ -61,7 +61,7 @@ with lib; type = types.attrsOf types.path; default = { }; example = literalExpression ''"{ examples = ''${env.sitePack}/IRkernel/kernelspec/kernel.js"; }''; - description = '' + description = lib.mdDoc '' Extra paths to link in kernel directory ''; }; diff --git a/nixos/modules/services/development/jupyterhub/default.nix b/nixos/modules/services/development/jupyterhub/default.nix index fa6b3be960a..bd8a5f0bd25 100644 --- a/nixos/modules/services/development/jupyterhub/default.nix +++ b/nixos/modules/services/development/jupyterhub/default.nix @@ -35,7 +35,7 @@ in { authentication = mkOption { type = types.str; default = "jupyterhub.auth.PAMAuthenticator"; - description = '' + description = lib.mdDoc '' Jupyterhub authentication to use There are many authenticators available including: oauth, pam, @@ -46,7 +46,7 @@ in { spawner = mkOption { type = types.str; default = "systemdspawner.SystemdSpawner"; - description = '' + description = lib.mdDoc '' Jupyterhub spawner to use There are many spawners available including: local process, @@ -57,7 +57,7 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra contents appended to the jupyterhub configuration Jupyterhub configuration is a normal python file using @@ -84,7 +84,7 @@ in { jupyterhub-systemdspawner ]) ''; - description = '' + description = lib.mdDoc '' Python environment to run jupyterhub Customizing will affect the packages available in the hub and @@ -106,7 +106,7 @@ in { jupyterlab ]) ''; - description = '' + description = lib.mdDoc '' Python environment to run jupyterlab Customizing will affect the packages available in the @@ -146,7 +146,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Declarative kernel config Kernels can be declared in any language that supports and has @@ -159,7 +159,7 @@ in { port = mkOption { type = types.port; default = 8000; - description = '' + description = lib.mdDoc '' Port number Jupyterhub will be listening on ''; }; @@ -167,7 +167,7 @@ in { host = mkOption { type = types.str; default = "0.0.0.0"; - description = '' + description = lib.mdDoc '' Bind IP JupyterHub will be listening on ''; }; @@ -175,7 +175,7 @@ in { stateDirectory = mkOption { type = types.str; default = "jupyterhub"; - description = '' + description = lib.mdDoc '' Directory for jupyterhub state (token + database) ''; }; diff --git a/nixos/modules/services/hardware/pcscd.nix b/nixos/modules/services/hardware/pcscd.nix index 827671fb68e..22e4ea49849 100644 --- a/nixos/modules/services/hardware/pcscd.nix +++ b/nixos/modules/services/hardware/pcscd.nix @@ -35,10 +35,10 @@ in LIBPATH /path/to/serial_reader.so CHANNELID 1 ''; - description = '' + description = lib.mdDoc '' Configuration for devices that aren't hotpluggable. - See <citerefentry><refentrytitle>reader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for valid options. + See {manpage}`reader.conf(5)` for valid options. ''; }; }; diff --git a/nixos/modules/services/logging/awstats.nix b/nixos/modules/services/logging/awstats.nix index 46054eade25..ad87c3bd907 100644 --- a/nixos/modules/services/logging/awstats.nix +++ b/nixos/modules/services/logging/awstats.nix @@ -121,9 +121,9 @@ in type = types.nullOr types.str; default = null; example = "hourly"; - description = '' + description = lib.mdDoc '' Specification of the time at which awstats will get updated. - (in the format described by <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) + (in the format described by {manpage}`systemd.time(7)`) ''; }; }; diff --git a/nixos/modules/services/mail/mlmmj.nix b/nixos/modules/services/mail/mlmmj.nix index 1d391b66597..642f8b20fe3 100644 --- a/nixos/modules/services/mail/mlmmj.nix +++ b/nixos/modules/services/mail/mlmmj.nix @@ -86,9 +86,9 @@ in maintInterval = mkOption { type = types.str; default = "20min"; - description = '' + description = lib.mdDoc '' Time interval between mlmmj-maintd runs, see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for format information. + {manpage}`systemd.time(7)` for format information. ''; }; diff --git a/nixos/modules/services/mail/postfix.nix b/nixos/modules/services/mail/postfix.nix index afb24a3187f..75ef09dbc6e 100644 --- a/nixos/modules/services/mail/postfix.nix +++ b/nixos/modules/services/mail/postfix.nix @@ -535,8 +535,8 @@ in canonical = mkOption { type = types.lines; default = ""; - description = '' - Entries for the <citerefentry><refentrytitle>canonical</refentrytitle><manvolnum>5</manvolnum></citerefentry> table. + description = lib.mdDoc '' + Entries for the {manpage}`canonical(5)` table. ''; }; diff --git a/nixos/modules/services/matrix/mjolnir.nix b/nixos/modules/services/matrix/mjolnir.nix index 278924b05cf..abbbb4030e5 100644 --- a/nixos/modules/services/matrix/mjolnir.nix +++ b/nixos/modules/services/matrix/mjolnir.nix @@ -70,27 +70,27 @@ in homeserverUrl = mkOption { type = types.str; default = "https://matrix.org"; - description = '' + description = lib.mdDoc '' Where the homeserver is located (client-server URL). - If <literal>pantalaimon.enable</literal> is <literal>true</literal>, this option will become the homeserver to which <literal>pantalaimon</literal> connects. - The listen address of <literal>pantalaimon</literal> will then become the <literal>homeserverUrl</literal> of <literal>mjolnir</literal>. + If `pantalaimon.enable` is `true`, this option will become the homeserver to which `pantalaimon` connects. + The listen address of `pantalaimon` will then become the `homeserverUrl` of `mjolnir`. ''; }; accessTokenFile = mkOption { type = with types; nullOr path; default = null; - description = '' - File containing the matrix access token for the <literal>mjolnir</literal> user. + description = lib.mdDoc '' + File containing the matrix access token for the `mjolnir` user. ''; }; pantalaimon = mkOption { - description = '' - <literal>pantalaimon</literal> options (enables E2E Encryption support). + description = lib.mdDoc '' + `pantalaimon` options (enables E2E Encryption support). - This will create a <literal>pantalaimon</literal> instance with the name "mjolnir". + This will create a `pantalaimon` instance with the name "mjolnir". ''; default = { }; type = types.submodule { @@ -102,22 +102,22 @@ in username = mkOption { type = types.str; - description = "The username to login with."; + description = lib.mdDoc "The username to login with."; }; passwordFile = mkOption { type = with types; nullOr path; default = null; - description = '' - File containing the matrix password for the <literal>mjolnir</literal> user. + description = lib.mdDoc '' + File containing the matrix password for the `mjolnir` user. ''; }; options = mkOption { type = types.submodule (import ./pantalaimon-options.nix); default = { }; - description = '' - passthrough additional options to the <literal>pantalaimon</literal> service. + description = lib.mdDoc '' + passthrough additional options to the `pantalaimon` service. ''; }; }; @@ -127,7 +127,7 @@ in dataPath = mkOption { type = types.path; default = "/var/lib/mjolnir"; - description = '' + description = lib.mdDoc '' The directory the bot should store various bits of information in. ''; }; @@ -135,11 +135,11 @@ in managementRoom = mkOption { type = types.str; default = "#moderators:example.org"; - description = '' + description = lib.mdDoc '' The room ID where people can use the bot. The bot has no access controls, so anyone in this room can use the bot - secure your room! This should be a room alias or room ID - not a matrix.to URL. - Note: <literal>mjolnir</literal> is fairly verbose - expect a lot of messages from it. + Note: `mjolnir` is fairly verbose - expect a lot of messages from it. ''; }; @@ -152,7 +152,7 @@ in "https://matrix.to/#/#anotherroom:example.org" ] ''; - description = '' + description = lib.mdDoc '' A list of rooms to protect (matrix.to URLs). ''; }; @@ -166,8 +166,8 @@ in automaticallyRedactForReasons = [ "spam" "advertising" ]; } ''; - description = '' - Additional settings (see <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">mjolnir default config</link> for available settings). These settings will override settings made by the module config. + description = lib.mdDoc '' + Additional settings (see [mjolnir default config](https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml) for available settings). These settings will override settings made by the module config. ''; }; }; diff --git a/nixos/modules/services/matrix/pantalaimon-options.nix b/nixos/modules/services/matrix/pantalaimon-options.nix index 035c57540d0..3945a70fc86 100644 --- a/nixos/modules/services/matrix/pantalaimon-options.nix +++ b/nixos/modules/services/matrix/pantalaimon-options.nix @@ -6,15 +6,15 @@ with lib; dataPath = mkOption { type = types.path; default = "/var/lib/pantalaimon-${name}"; - description = '' - The directory where <literal>pantalaimon</literal> should store its state such as the database file. + description = lib.mdDoc '' + The directory where `pantalaimon` should store its state such as the database file. ''; }; logLevel = mkOption { type = types.enum [ "info" "warning" "error" "debug" ]; default = "warning"; - description = '' + description = lib.mdDoc '' Set the log level of the daemon. ''; }; @@ -22,8 +22,8 @@ with lib; homeserver = mkOption { type = types.str; example = "https://matrix.org"; - description = '' - The URI of the homeserver that the <literal>pantalaimon</literal> proxy should + description = lib.mdDoc '' + The URI of the homeserver that the `pantalaimon` proxy should forward requests to, without the matrix API path but including the http(s) schema. ''; @@ -32,7 +32,7 @@ with lib; ssl = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether or not SSL verification should be enabled for outgoing connections to the homeserver. ''; @@ -41,7 +41,7 @@ with lib; listenAddress = mkOption { type = types.str; default = "localhost"; - description = '' + description = lib.mdDoc '' The address where the daemon will listen to client connections for this homeserver. ''; @@ -50,7 +50,7 @@ with lib; listenPort = mkOption { type = types.port; default = 8009; - description = '' + description = lib.mdDoc '' The port where the daemon will listen to client connections for this homeserver. Note that the listen address/port combination needs to be unique between different homeservers. @@ -60,9 +60,9 @@ with lib; extraSettings = mkOption { type = types.attrs; default = { }; - description = '' + description = lib.mdDoc '' Extra configuration options. See - <link xlink:href="https://github.com/matrix-org/pantalaimon/blob/master/docs/man/pantalaimon.5.md">pantalaimon(5)</link> + [pantalaimon(5)](https://github.com/matrix-org/pantalaimon/blob/master/docs/man/pantalaimon.5.md) for available options. ''; }; diff --git a/nixos/modules/services/matrix/pantalaimon.nix b/nixos/modules/services/matrix/pantalaimon.nix index 63b40099ca5..591ba9a7ab5 100644 --- a/nixos/modules/services/matrix/pantalaimon.nix +++ b/nixos/modules/services/matrix/pantalaimon.nix @@ -51,11 +51,11 @@ in options.services.pantalaimon-headless.instances = mkOption { default = { }; type = types.attrsOf (types.submodule (import ./pantalaimon-options.nix)); - description = '' + description = lib.mdDoc '' Declarative instance config. Note: to use pantalaimon interactively, e.g. for a Matrix client which does not - support End-to-end encryption (like <literal>fractal</literal>), refer to the home-manager module. + support End-to-end encryption (like `fractal`), refer to the home-manager module. ''; }; diff --git a/nixos/modules/services/matrix/synapse.nix b/nixos/modules/services/matrix/synapse.nix index 3d5d10cdf07..0dbfcc17638 100644 --- a/nixos/modules/services/matrix/synapse.nix +++ b/nixos/modules/services/matrix/synapse.nix @@ -143,7 +143,7 @@ in { configFile = mkOption { type = types.path; readOnly = true; - description = '' + description = lib.mdDoc '' Path to the configuration file on the target system. Useful to configure e.g. workers that also need this. ''; @@ -153,7 +153,7 @@ in { type = types.package; default = pkgs.matrix-synapse; defaultText = literalExpression "pkgs.matrix-synapse"; - description = '' + description = lib.mdDoc '' Overridable attribute of the matrix synapse server package to use. ''; }; @@ -167,7 +167,7 @@ in { matrix-synapse-pam ]; ''; - description = '' + description = lib.mdDoc '' List of additional Matrix plugins to make available. ''; }; @@ -175,7 +175,7 @@ in { withJemalloc = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to preload jemalloc to reduce memory fragmentation and overall usage. ''; }; @@ -183,7 +183,7 @@ in { dataDir = mkOption { type = types.str; default = "/var/lib/matrix-synapse"; - description = '' + description = lib.mdDoc '' The directory where matrix-synapse stores its stateful data such as certificates, media and uploads. ''; @@ -210,7 +210,7 @@ in { example = "example.com"; default = config.networking.hostName; defaultText = literalExpression "config.networking.hostName"; - description = '' + description = lib.mdDoc '' The domain name of the server, with optional explicit port. This is used by remote servers to look up the server address. This is also the last part of your UserID. @@ -222,7 +222,7 @@ in { enable_registration = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable registration for new users. ''; }; @@ -253,7 +253,7 @@ in { enable_metrics = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable collection and rendering of performance metrics ''; }; @@ -261,7 +261,7 @@ in { report_stats = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether or not to report anonymized homeserver usage statistics. ''; }; @@ -269,7 +269,7 @@ in { signing_key_path = mkOption { type = types.path; default = "${cfg.dataDir}/homeserver.signing.key"; - description = '' + description = lib.mdDoc '' Path to the signing key to sign messages with. ''; }; @@ -278,7 +278,7 @@ in { type = types.path; default = "/run/matrix-synapse.pid"; readOnly = true; - description = '' + description = lib.mdDoc '' The file to store the PID in. ''; }; @@ -286,7 +286,7 @@ in { log_config = mkOption { type = types.path; default = ./synapse-log_config.yaml; - description = '' + description = lib.mdDoc '' The file that holds the logging configuration. ''; }; @@ -297,7 +297,7 @@ in { then "${cfg.dataDir}/media_store" else "${cfg.dataDir}/media"; defaultText = "${cfg.dataDir}/media_store for when system.stateVersion is at least 22.05, ${cfg.dataDir}/media when lower than 22.05"; - description = '' + description = lib.mdDoc '' Directory where uploaded images and attachments are stored. ''; }; @@ -306,7 +306,7 @@ in { type = types.nullOr types.str; default = null; example = "https://example.com:8448/"; - description = '' + description = lib.mdDoc '' The public-facing base URL for the client API (not including _matrix/...) ''; }; @@ -315,7 +315,7 @@ in { type = types.nullOr types.str; default = null; example = "/var/lib/acme/example.com/fullchain.pem"; - description = '' + description = lib.mdDoc '' PEM encoded X509 certificate for TLS. You can replace the self-signed certificate that synapse autogenerates on launch with your own SSL certificate + key pair @@ -328,7 +328,7 @@ in { type = types.nullOr types.str; default = null; example = "/var/lib/acme/example.com/key.pem"; - description = '' + description = lib.mdDoc '' PEM encoded private key for TLS. Specify null if synapse is not speaking TLS directly. ''; @@ -338,7 +338,7 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' Whether to enable presence tracking. Presence tracking allows users to see the state (e.g online/offline) @@ -352,7 +352,7 @@ in { port = mkOption { type = types.port; example = 8448; - description = '' + description = lib.mdDoc '' The port to listen for HTTP(S) requests on. ''; }; @@ -369,7 +369,7 @@ in { "0.0.0.0" ] ''; - description = '' + description = lib.mdDoc '' IP addresses to bind the listener to. ''; }; @@ -383,7 +383,7 @@ in { ]; default = "http"; example = "metrics"; - description = '' + description = lib.mdDoc '' The type of the listener, usually http. ''; }; @@ -392,7 +392,7 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' Whether to enable TLS on the listener socket. ''; }; @@ -401,7 +401,7 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Use the X-Forwarded-For (XFF) header as the client IP and not the actual client IP. ''; @@ -422,7 +422,7 @@ in { "replication" "static" ]); - description = '' + description = lib.mdDoc '' List of resources to host on this listener. ''; example = [ @@ -431,7 +431,7 @@ in { }; compress = mkOption { type = types.bool; - description = '' + description = lib.mdDoc '' Should synapse compress HTTP responses to clients that support it? This should be disabled if running synapse behind a load balancer that can do automatic compression. @@ -439,7 +439,7 @@ in { }; }; }); - description = '' + description = lib.mdDoc '' List of HTTP resources to serve on this listener. ''; }; @@ -459,7 +459,7 @@ in { compress = false; } ]; } ]; - description = '' + description = lib.mdDoc '' List of ports that Synapse should listen on, their purpose and their configuration. ''; }; @@ -477,7 +477,7 @@ in { then "psycopg2" else "sqlite3" ''; - description = '' + description = lib.mdDoc '' The database engine name. Can be sqlite3 or psycopg2. ''; }; @@ -494,7 +494,7 @@ in { psycopg2 = "matrix-synapse"; }.''${${options.services.matrix-synapse.settings}.database.name}; ''; - description = '' + description = lib.mdDoc '' Name of the database when using the psycopg2 backend, path to the database location when using sqlite3. ''; @@ -506,7 +506,7 @@ in { sqlite3 = null; psycopg2 = "matrix-synapse"; }.${cfg.settings.database.name}; - description = '' + description = lib.mdDoc '' Username to connect with psycopg2, set to null when using sqlite3. ''; @@ -546,7 +546,7 @@ in { "fec0::/10" "ff00::/8" ]; - description = '' + description = lib.mdDoc '' List of IP address CIDR ranges that the URL preview spider is denied from accessing. ''; @@ -555,7 +555,7 @@ in { url_preview_ip_range_whitelist = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' List of IP address CIDR ranges that the URL preview spider is allowed to access even if they are specified in url_preview_ip_range_blacklist. ''; @@ -564,7 +564,7 @@ in { url_preview_url_blacklist = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Optional list of URL matches that the URL preview spider is denied from accessing. ''; @@ -574,7 +574,7 @@ in { type = types.str; default = "50M"; example = "100M"; - description = '' + description = lib.mdDoc '' The largest allowed upload size in bytes ''; }; @@ -583,7 +583,7 @@ in { type = types.str; default = "32M"; example = "64M"; - description = '' + description = lib.mdDoc '' Maximum number of pixels that will be thumbnailed ''; }; @@ -592,7 +592,7 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to generate new thumbnails on the fly to precisely match the resolution requested by the client. If true then whenever a new resolution is requested by the client the server will @@ -610,7 +610,7 @@ in { "turns:turn.example.com:5349?transport=udp" "turns:turn.example.com:5349?transport=tcp" ]; - description = '' + description = lib.mdDoc '' The public URIs of the TURN server to give to clients ''; }; @@ -633,7 +633,7 @@ in { server_name = mkOption { type = types.str; example = "matrix.org"; - description = '' + description = lib.mdDoc '' Hostname of the trusted server. ''; }; @@ -646,7 +646,7 @@ in { "ed25519:auto" = "Noi6WqcDj0QmPxCNQqgezwTlBKrfqehY1u2FyWP9uYw"; } ''; - description = '' + description = lib.mdDoc '' Attribute set from key id to base64 encoded public key. If specified synapse will check that the response is signed @@ -661,7 +661,7 @@ in { "ed25519:auto" = "Noi6WqcDj0QmPxCNQqgezwTlBKrfqehY1u2FyWP9uYw"; }; } ]; - description = '' + description = lib.mdDoc '' The trusted servers to download signing keys from. ''; }; @@ -669,7 +669,7 @@ in { app_service_config_files = mkOption { type = types.listOf types.path; default = [ ]; - description = '' + description = lib.mdDoc '' A list of application service config file to use ''; }; @@ -681,7 +681,7 @@ in { extraConfigFiles = mkOption { type = types.listOf types.path; default = []; - description = '' + description = lib.mdDoc '' Extra config files to include. The configuration files will be included based on the command line diff --git a/nixos/modules/services/misc/autorandr.nix b/nixos/modules/services/misc/autorandr.nix index 079b2b39579..06f24d7c7e7 100644 --- a/nixos/modules/services/misc/autorandr.nix +++ b/nixos/modules/services/misc/autorandr.nix @@ -114,9 +114,9 @@ let [ 0.0 0.0 1.0 ] ] ''; - description = '' + description = lib.mdDoc '' Refer to - <citerefentry><refentrytitle>xrandr</refentrytitle><manvolnum>1</manvolnum></citerefentry> + {manpage}`xrandr(1)` for the documentation of the transform matrix. ''; }; diff --git a/nixos/modules/services/misc/docker-registry.nix b/nixos/modules/services/misc/docker-registry.nix index 734a7f6c87d..7a9907fd351 100644 --- a/nixos/modules/services/misc/docker-registry.nix +++ b/nixos/modules/services/misc/docker-registry.nix @@ -103,9 +103,9 @@ in { garbageCollectDates = mkOption { default = "daily"; type = types.str; - description = '' + description = lib.mdDoc '' Specification (in the format described by - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at + {manpage}`systemd.time(7)`) of the time at which the garbage collect will occur. ''; }; diff --git a/nixos/modules/services/misc/fstrim.nix b/nixos/modules/services/misc/fstrim.nix index 6d57cef350d..83e7ca359b2 100644 --- a/nixos/modules/services/misc/fstrim.nix +++ b/nixos/modules/services/misc/fstrim.nix @@ -16,12 +16,12 @@ in { interval = mkOption { type = types.str; default = "weekly"; - description = '' + description = lib.mdDoc '' How often we run fstrim. For most desktop and server systems a sufficient trimming frequency is once a week. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; }; diff --git a/nixos/modules/services/misc/geoipupdate.nix b/nixos/modules/services/misc/geoipupdate.nix index 68c6bf69a22..c2007f25fb3 100644 --- a/nixos/modules/services/misc/geoipupdate.nix +++ b/nixos/modules/services/misc/geoipupdate.nix @@ -19,10 +19,10 @@ in interval = lib.mkOption { type = lib.types.str; default = "weekly"; - description = '' + description = lib.mdDoc '' Update the GeoIP databases at this time / interval. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/misc/gitea.nix b/nixos/modules/services/misc/gitea.nix index 91cf0bc6ed0..257143bfdc1 100644 --- a/nixos/modules/services/misc/gitea.nix +++ b/nixos/modules/services/misc/gitea.nix @@ -162,11 +162,11 @@ in type = types.str; default = "04:31"; example = "hourly"; - description = '' + description = lib.mdDoc '' Run a gitea dump at this interval. Runs by default at 04:31 every day. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/misc/gitit.nix b/nixos/modules/services/misc/gitit.nix index 223fa76d910..f00c03337d9 100644 --- a/nixos/modules/services/misc/gitit.nix +++ b/nixos/modules/services/misc/gitit.nix @@ -31,14 +31,14 @@ let enable = mkOption { type = types.bool; default = false; - description = "Enable the gitit service."; + description = lib.mdDoc "Enable the gitit service."; }; haskellPackages = mkOption { default = pkgs.haskellPackages; defaultText = literalExpression "pkgs.haskellPackages"; example = literalExpression "pkgs.haskell.packages.ghc784"; - description = "haskellPackages used to build gitit and plugins."; + description = lib.mdDoc "haskellPackages used to build gitit and plugins."; }; extraPackages = mkOption { @@ -59,31 +59,31 @@ let address = mkOption { type = types.str; default = "0.0.0.0"; - description = "IP address on which the web server will listen."; + description = lib.mdDoc "IP address on which the web server will listen."; }; port = mkOption { type = types.int; default = 5001; - description = "Port on which the web server will run."; + description = lib.mdDoc "Port on which the web server will run."; }; wikiTitle = mkOption { type = types.str; default = "Gitit!"; - description = "The wiki title."; + description = lib.mdDoc "The wiki title."; }; repositoryType = mkOption { type = types.enum ["git" "darcs" "mercurial"]; default = "git"; - description = "Specifies the type of repository used for wiki content."; + description = lib.mdDoc "Specifies the type of repository used for wiki content."; }; repositoryPath = mkOption { type = types.path; default = homeDir + "/wiki"; - description = '' + description = lib.mdDoc '' Specifies the path of the repository directory. If it does not exist, gitit will create it on startup. ''; @@ -92,7 +92,7 @@ let requireAuthentication = mkOption { type = types.enum [ "none" "modify" "read" ]; default = "modify"; - description = '' + description = lib.mdDoc '' If 'none', login is never required, and pages can be edited anonymously. If 'modify', login is required to modify the wiki (edit, add, delete pages, upload files). If 'read', login is @@ -103,7 +103,7 @@ let authenticationMethod = mkOption { type = types.enum [ "form" "http" "generic" "github" ]; default = "form"; - description = '' + description = lib.mdDoc '' 'form' means that users will be logged in and registered using forms in the gitit web interface. 'http' means that gitit will assume that HTTP authentication is in place and take the logged in username from @@ -121,7 +121,7 @@ let userFile = mkOption { type = types.path; default = homeDir + "/gitit-users"; - description = '' + description = lib.mdDoc '' Specifies the path of the file containing user login information. If it does not exist, gitit will create it (with an empty user list). This file is not used if 'http' is selected for @@ -132,7 +132,7 @@ let sessionTimeout = mkOption { type = types.int; default = 60; - description = '' + description = lib.mdDoc '' Number of minutes of inactivity before a session expires. ''; }; @@ -140,7 +140,7 @@ let staticDir = mkOption { type = types.path; default = gititShared + "/data/static"; - description = '' + description = lib.mdDoc '' Specifies the path of the static directory (containing javascript, css, and images). If it does not exist, gitit will create it and populate it with required scripts, stylesheets, and images. @@ -150,7 +150,7 @@ let defaultPageType = mkOption { type = types.enum [ "markdown" "rst" "latex" "html" "markdown+lhs" "rst+lhs" "latex+lhs" ]; default = "markdown"; - description = '' + description = lib.mdDoc '' Specifies the type of markup used to interpret pages in the wiki. Possible values are markdown, rst, latex, html, markdown+lhs, rst+lhs, and latex+lhs. (the +lhs variants treat the input as @@ -166,7 +166,7 @@ let math = mkOption { type = types.enum [ "mathml" "raw" "mathjax" "jsmath" "google" ]; default = "mathml"; - description = '' + description = lib.mdDoc '' Specifies how LaTeX math is to be displayed. Possible values are mathml, raw, mathjax, jsmath, and google. If mathml is selected, gitit will convert LaTeX math to MathML and link in a script, @@ -186,7 +186,7 @@ let mathJaxScript = mkOption { type = types.str; default = "https://d3eoax9i5htok0.cloudfront.net/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; - description = '' + description = lib.mdDoc '' Specifies the path to MathJax rendering script. You might want to use your own MathJax script to render formulas without Internet connection or if you want to use some special LaTeX packages. Note: @@ -202,7 +202,7 @@ let showLhsBirdTracks = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Specifies whether to show Haskell code blocks in "bird style", with "> " at the beginning of each line. ''; @@ -224,7 +224,7 @@ let logFile = mkOption { type = types.path; default = homeDir + "/gitit.log"; - description = '' + description = lib.mdDoc '' Specifies the path of gitit's log file. If it does not exist, gitit will create it. The log is in Apache combined log format. ''; @@ -233,7 +233,7 @@ let logLevel = mkOption { type = types.enum [ "DEBUG" "INFO" "NOTICE" "WARNING" "ERROR" "CRITICAL" "ALERT" "EMERGENCY" ]; default = "ERROR"; - description = '' + description = lib.mdDoc '' Determines how much information is logged. Possible values (from most to least verbose) are DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY. @@ -243,7 +243,7 @@ let frontPage = mkOption { type = types.str; default = "Front Page"; - description = '' + description = lib.mdDoc '' Specifies which wiki page is to be used as the wiki's front page. Gitit creates a default front page on startup, if one does not exist already. @@ -253,7 +253,7 @@ let noDelete = mkOption { type = types.str; default = "Front Page, Help"; - description = '' + description = lib.mdDoc '' Specifies pages that cannot be deleted through the web interface. (They can still be deleted directly using git or darcs.) A comma-separated list of page names. Leave blank to allow every page @@ -264,7 +264,7 @@ let noEdit = mkOption { type = types.str; default = "Help"; - description = '' + description = lib.mdDoc '' Specifies pages that cannot be edited through the web interface. Leave blank to allow every page to be edited. ''; @@ -273,7 +273,7 @@ let defaultSummary = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' Specifies text to be used in the change description if the author leaves the "description" field blank. If default-summary is blank (the default), the author will be required to fill in the description @@ -284,7 +284,7 @@ let tableOfContents = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Specifies whether to print a tables of contents (with links to sections) on each wiki page. ''; @@ -293,7 +293,7 @@ let plugins = mkOption { type = with types; listOf str; default = [ (gititShared + "/plugins/Dot.hs") ]; - description = '' + description = lib.mdDoc '' Specifies a list of plugins to load. Plugins may be specified either by their path or by their module name. If the plugin name starts with Gitit.Plugin., gitit will assume that the plugin is an installed @@ -304,7 +304,7 @@ let useCache = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Specifies whether to cache rendered pages. Note that if use-feed is selected, feeds will be cached regardless of the value of use-cache. ''; @@ -313,13 +313,13 @@ let cacheDir = mkOption { type = types.path; default = homeDir + "/cache"; - description = "Path where rendered pages will be cached."; + description = lib.mdDoc "Path where rendered pages will be cached."; }; maxUploadSize = mkOption { type = types.str; default = "1000K"; - description = '' + description = lib.mdDoc '' Specifies an upper limit on the size (in bytes) of files uploaded through the wiki's web interface. To disable uploads, set this to 0K. This will result in the uploads link disappearing and the @@ -330,19 +330,19 @@ let maxPageSize = mkOption { type = types.str; default = "1000K"; - description = "Specifies an upper limit on the size (in bytes) of pages."; + description = lib.mdDoc "Specifies an upper limit on the size (in bytes) of pages."; }; debugMode = mkOption { type = types.bool; default = false; - description = "Causes debug information to be logged while gitit is running."; + description = lib.mdDoc "Causes debug information to be logged while gitit is running."; }; compressResponses = mkOption { type = types.bool; default = true; - description = "Specifies whether HTTP responses should be compressed."; + description = lib.mdDoc "Specifies whether HTTP responses should be compressed."; }; mimeTypesFile = mkOption { @@ -363,7 +363,7 @@ video/x-ms-wmx wmx useReCaptcha = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If true, causes gitit to use the reCAPTCHA service (http://recaptcha.net) to prevent bots from creating accounts. ''; @@ -372,7 +372,7 @@ video/x-ms-wmx wmx reCaptchaPrivateKey = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Specifies the private key for the reCAPTCHA service. To get these, you need to create an account at http://recaptcha.net. ''; @@ -381,7 +381,7 @@ video/x-ms-wmx wmx reCaptchaPublicKey = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Specifies the public key for the reCAPTCHA service. To get these, you need to create an account at http://recaptcha.net. ''; @@ -390,7 +390,7 @@ video/x-ms-wmx wmx accessQuestion = mkOption { type = types.str; default = "What is the code given to you by Ms. X?"; - description = '' + description = lib.mdDoc '' Specifies a question that users must answer when they attempt to create an account ''; @@ -399,7 +399,7 @@ video/x-ms-wmx wmx accessQuestionAnswers = mkOption { type = types.str; default = "RED DOG, red dog"; - description = '' + description = lib.mdDoc '' Specifies a question that users must answer when they attempt to create an account, along with a comma-separated list of acceptable answers. This can be used to institute a rudimentary password for @@ -413,7 +413,7 @@ video/x-ms-wmx wmx rpxDomain = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Specifies the domain and key of your RPX account. The domain is just the prefix of the complete RPX domain, so if your full domain is 'https://foo.rpxnow.com/', use 'foo' as the value of rpx-domain. @@ -423,13 +423,13 @@ video/x-ms-wmx wmx rpxKey = mkOption { type = with types; nullOr str; default = null; - description = "RPX account access key."; + description = lib.mdDoc "RPX account access key."; }; mailCommand = mkOption { type = types.str; default = "sendmail %s"; - description = '' + description = lib.mdDoc '' Specifies the command to use to send notification emails. '%s' will be replaced by the destination email address. The body of the message will be read from stdin. If this field is left blank, @@ -451,7 +451,7 @@ video/x-ms-wmx wmx > > Regards ''; - description = '' + description = lib.mdDoc '' Gives the text of the message that will be sent to the user should she want to reset her password, or change other registration info. The lines must be indented, and must begin with '>'. The initial @@ -471,7 +471,7 @@ video/x-ms-wmx wmx useFeed = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Specifies whether an ATOM feed should be enabled (for the site and for individual pages). ''; @@ -480,7 +480,7 @@ video/x-ms-wmx wmx baseUrl = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' The base URL of the wiki, to be used in constructing feed IDs and RPX token_urls. Set this if useFeed is false or authentication-method is 'rpx'. @@ -502,19 +502,19 @@ video/x-ms-wmx wmx feedDays = mkOption { type = types.int; default = 14; - description = "Number of days to be included in feeds."; + description = lib.mdDoc "Number of days to be included in feeds."; }; feedRefreshTime = mkOption { type = types.int; default = 60; - description = "Number of minutes to cache feeds before refreshing."; + description = lib.mdDoc "Number of minutes to cache feeds before refreshing."; }; pdfExport = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If true, PDF will appear in export options. PDF will be created using pdflatex, which must be installed and in the path. Note that PDF exports create significant additional server load. @@ -524,7 +524,7 @@ video/x-ms-wmx wmx pandocUserData = mkOption { type = with types; nullOr path; default = null; - description = '' + description = lib.mdDoc '' If a directory is specified, this will be searched for pandoc customizations. These can include a templates/ directory for custom templates for various export formats, an S5 directory for custom S5 @@ -537,7 +537,7 @@ video/x-ms-wmx wmx xssSanitize = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' If true, all HTML (including that produced by pandoc) is filtered through xss-sanitize. Set to no only if you trust all of your users. ''; @@ -546,37 +546,37 @@ video/x-ms-wmx wmx oauthClientId = mkOption { type = with types; nullOr str; default = null; - description = "OAuth client ID"; + description = lib.mdDoc "OAuth client ID"; }; oauthClientSecret = mkOption { type = with types; nullOr str; default = null; - description = "OAuth client secret"; + description = lib.mdDoc "OAuth client secret"; }; oauthCallback = mkOption { type = with types; nullOr str; default = null; - description = "OAuth callback URL"; + description = lib.mdDoc "OAuth callback URL"; }; oauthAuthorizeEndpoint = mkOption { type = with types; nullOr str; default = null; - description = "OAuth authorize endpoint"; + description = lib.mdDoc "OAuth authorize endpoint"; }; oauthAccessTokenEndpoint = mkOption { type = with types; nullOr str; default = null; - description = "OAuth access token endpoint"; + description = lib.mdDoc "OAuth access token endpoint"; }; githubOrg = mkOption { type = with types; nullOr str; default = null; - description = "Github organization"; + description = lib.mdDoc "Github organization"; }; }; diff --git a/nixos/modules/services/misc/gitlab.nix b/nixos/modules/services/misc/gitlab.nix index 4e7ecfc0397..0bf2bca4a0b 100644 --- a/nixos/modules/services/misc/gitlab.nix +++ b/nixos/modules/services/misc/gitlab.nix @@ -319,10 +319,10 @@ in { type = with types; either str (listOf str); default = []; example = "03:00"; - description = '' + description = lib.mdDoc '' The time(s) to run automatic backup of GitLab state. Specified in systemd's time format; see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/misc/nix-daemon.nix b/nixos/modules/services/misc/nix-daemon.nix index 9bac7a68ad2..d299c4a0a8f 100644 --- a/nixos/modules/services/misc/nix-daemon.nix +++ b/nixos/modules/services/misc/nix-daemon.nix @@ -155,29 +155,29 @@ in type = types.enum [ "other" "batch" "idle" ]; default = "other"; example = "batch"; - description = '' + description = lib.mdDoc '' Nix daemon process CPU scheduling policy. This policy propagates to - build processes. <literal>other</literal> is the default scheduling - policy for regular tasks. The <literal>batch</literal> policy is - similar to <literal>other</literal>, but optimised for - non-interactive tasks. <literal>idle</literal> is for extremely + build processes. `other` is the default scheduling + policy for regular tasks. The `batch` policy is + similar to `other`, but optimised for + non-interactive tasks. `idle` is for extremely low-priority tasks that should only be run when no other task requires CPU time. - Please note that while using the <literal>idle</literal> policy may + Please note that while using the `idle` policy may greatly improve responsiveness of a system performing expensive builds, it may also slow down and potentially starve crucial configuration updates during load. - <literal>idle</literal> may therefore be a sensible policy for + `idle` may therefore be a sensible policy for systems that experience only intermittent phases of high CPU load, such as desktop or portable computers used interactively. Other - systems should use the <literal>other</literal> or - <literal>batch</literal> policy instead. + systems should use the `other` or + `batch` policy instead. For more fine-grained resource control, please refer to - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> and adjust - <option>systemd.services.nix-daemon</option> directly. + {manpage}`systemd.resource-control(5)` and adjust + {option}`systemd.services.nix-daemon` directly. ''; }; diff --git a/nixos/modules/services/misc/nix-gc.nix b/nixos/modules/services/misc/nix-gc.nix index a03c0e8a901..97596d28cd8 100644 --- a/nixos/modules/services/misc/nix-gc.nix +++ b/nixos/modules/services/misc/nix-gc.nix @@ -24,12 +24,12 @@ in type = types.str; default = "03:15"; example = "weekly"; - description = '' + description = lib.mdDoc '' How often or when garbage collection is performed. For most desktop and server systems a sufficient garbage collection is once a week. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; @@ -37,11 +37,11 @@ in default = "0"; type = types.str; example = "45min"; - description = '' + description = lib.mdDoc '' Add a randomized delay before each garbage collection. The delay will be chosen between zero and this value. This value must be a time span in the format specified by - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + {manpage}`systemd.time(7)` ''; }; diff --git a/nixos/modules/services/misc/nix-optimise.nix b/nixos/modules/services/misc/nix-optimise.nix index ebb0bc543ef..db8148c060e 100644 --- a/nixos/modules/services/misc/nix-optimise.nix +++ b/nixos/modules/services/misc/nix-optimise.nix @@ -23,9 +23,9 @@ in dates = mkOption { default = ["03:45"]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' Specification (in the format described by - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at + {manpage}`systemd.time(7)`) of the time at which the optimiser will run. ''; }; diff --git a/nixos/modules/services/misc/snapper.nix b/nixos/modules/services/misc/snapper.nix index 0afd84a5082..cfdfa2830ce 100644 --- a/nixos/modules/services/misc/snapper.nix +++ b/nixos/modules/services/misc/snapper.nix @@ -20,22 +20,22 @@ in snapshotInterval = mkOption { type = types.str; default = "hourly"; - description = '' + description = lib.mdDoc '' Snapshot interval. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; cleanupInterval = mkOption { type = types.str; default = "1d"; - description = '' + description = lib.mdDoc '' Cleanup interval. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix index de04797a800..113c53f7395 100644 --- a/nixos/modules/services/misc/sourcehut/default.nix +++ b/nixos/modules/services/misc/sourcehut/default.nix @@ -47,33 +47,33 @@ let }))); commonServiceSettings = srv: { origin = mkOption { - description = "URL ${srv}.sr.ht is being served at (protocol://domain)"; + description = lib.mdDoc "URL ${srv}.sr.ht is being served at (protocol://domain)"; type = types.str; default = "https://${srv}.${domain}"; defaultText = "https://${srv}.example.com"; }; debug-host = mkOption { - description = "Address to bind the debug server to."; + description = lib.mdDoc "Address to bind the debug server to."; type = with types; nullOr str; default = null; }; debug-port = mkOption { - description = "Port to bind the debug server to."; + description = lib.mdDoc "Port to bind the debug server to."; type = with types; nullOr str; default = null; }; connection-string = mkOption { - description = "SQLAlchemy connection string for the database."; + description = lib.mdDoc "SQLAlchemy connection string for the database."; type = types.str; default = "postgresql:///localhost?user=${srv}srht&host=/run/postgresql"; }; migrate-on-upgrade = mkEnableOption "automatic migrations on package upgrade" // { default = true; }; oauth-client-id = mkOption { - description = "${srv}.sr.ht's OAuth client id for meta.sr.ht."; + description = lib.mdDoc "${srv}.sr.ht's OAuth client id for meta.sr.ht."; type = types.str; }; oauth-client-secret = mkOption { - description = "${srv}.sr.ht's OAuth client secret for meta.sr.ht."; + description = lib.mdDoc "${srv}.sr.ht's OAuth client secret for meta.sr.ht."; type = types.path; apply = s: "<" + toString s; }; @@ -117,7 +117,7 @@ in type = with types; listOf (enum [ "builds" "dispatch" "git" "hg" "hub" "lists" "man" "meta" "pages" "paste" "todo" ]); defaultText = "locally enabled services"; - description = '' + description = lib.mdDoc '' Services that may be displayed as links in the title bar of the Web interface. ''; }; @@ -125,7 +125,7 @@ in listenAddress = mkOption { type = types.str; default = "localhost"; - description = "Address to bind to."; + description = lib.mdDoc "Address to bind to."; }; python = mkOption { @@ -147,7 +147,7 @@ in virtualHost = mkOption { type = types.attrs; default = {}; - description = "Virtual-host configuration merged with all Sourcehut's virtual-hosts."; + description = lib.mdDoc "Virtual-host configuration merged with all Sourcehut's virtual-hosts."; }; }; @@ -168,48 +168,48 @@ in freeformType = settingsFormat.type; options."sr.ht" = { global-domain = mkOption { - description = "Global domain name."; + description = lib.mdDoc "Global domain name."; type = types.str; example = "example.com"; }; environment = mkOption { - description = "Values other than \"production\" adds a banner to each page."; + description = lib.mdDoc "Values other than \"production\" adds a banner to each page."; type = types.enum [ "development" "production" ]; default = "development"; }; network-key = mkOption { - description = '' + description = lib.mdDoc '' An absolute file path (which should be outside the Nix-store) - to a secret key to encrypt internal messages with. Use <literal>srht-keygen network</literal> to + to a secret key to encrypt internal messages with. Use `srht-keygen network` to generate this key. It must be consistent between all services and nodes. ''; type = types.path; apply = s: "<" + toString s; }; owner-email = mkOption { - description = "Owner's email."; + description = lib.mdDoc "Owner's email."; type = types.str; default = "contact@example.com"; }; owner-name = mkOption { - description = "Owner's name."; + description = lib.mdDoc "Owner's name."; type = types.str; default = "John Doe"; }; site-blurb = mkOption { - description = "Blurb for your site."; + description = lib.mdDoc "Blurb for your site."; type = types.str; default = "the hacker's forge"; }; site-info = mkOption { - description = "The top-level info page for your site."; + description = lib.mdDoc "The top-level info page for your site."; type = types.str; default = "https://sourcehut.org"; }; service-key = mkOption { - description = '' + description = lib.mdDoc '' An absolute file path (which should be outside the Nix-store) - to a key used for encrypting session cookies. Use <literal>srht-keygen service</literal> to + to a key used for encrypting session cookies. Use `srht-keygen service` to generate the service key. This must be shared between each node of the same service (e.g. git1.sr.ht and git2.sr.ht), but different services may use different keys. If you configure all of your services with the same @@ -219,12 +219,12 @@ in apply = s: "<" + toString s; }; site-name = mkOption { - description = "The name of your network of sr.ht-based sites."; + description = lib.mdDoc "The name of your network of sr.ht-based sites."; type = types.str; default = "sourcehut"; }; source-url = mkOption { - description = "The source code for your fork of sr.ht."; + description = lib.mdDoc "The source code for your fork of sr.ht."; type = types.str; default = "https://git.sr.ht/~sircmpwn/srht"; }; @@ -232,7 +232,7 @@ in options.mail = { smtp-host = mkOptionNullOrStr "Outgoing SMTP host."; smtp-port = mkOption { - description = "Outgoing SMTP port."; + description = lib.mdDoc "Outgoing SMTP port."; type = with types; nullOr port; default = null; }; @@ -240,44 +240,44 @@ in smtp-password = mkOptionNullOrStr "Outgoing SMTP password."; smtp-from = mkOption { type = types.str; - description = "Outgoing SMTP FROM."; + description = lib.mdDoc "Outgoing SMTP FROM."; }; error-to = mkOptionNullOrStr "Address receiving application exceptions"; error-from = mkOptionNullOrStr "Address sending application exceptions"; pgp-privkey = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' An absolute file path (which should be outside the Nix-store) to an OpenPGP private key. Your PGP key information (DO NOT mix up pub and priv here) You must remove the password from your secret key, if present. - You can do this with <literal>gpg --edit-key [key-id]</literal>, - then use the <literal>passwd</literal> command and do not enter a new password. + You can do this with `gpg --edit-key [key-id]`, + then use the `passwd` command and do not enter a new password. ''; }; pgp-pubkey = mkOption { type = with types; either path str; - description = "OpenPGP public key."; + description = lib.mdDoc "OpenPGP public key."; }; pgp-key-id = mkOption { type = types.str; - description = "OpenPGP key identifier."; + description = lib.mdDoc "OpenPGP key identifier."; }; }; options.objects = { s3-upstream = mkOption { - description = "Configure the S3-compatible object storage service."; + description = lib.mdDoc "Configure the S3-compatible object storage service."; type = with types; nullOr str; default = null; }; s3-access-key = mkOption { - description = "Access key to the S3-compatible object storage service"; + description = lib.mdDoc "Access key to the S3-compatible object storage service"; type = with types; nullOr str; default = null; }; s3-secret-key = mkOption { - description = '' + description = lib.mdDoc '' An absolute file path (which should be outside the Nix-store) to the secret key of the S3-compatible object storage service. ''; @@ -288,13 +288,13 @@ in }; options.webhooks = { private-key = mkOption { - description = '' + description = lib.mdDoc '' An absolute file path (which should be outside the Nix-store) to a base64-encoded Ed25519 key for signing webhook payloads. This should be consistent for all *.sr.ht sites, as this key will be used to verify signatures from other sites in your network. - Use the <literal>srht-keygen webhook</literal> command to generate a key. + Use the `srht-keygen webhook` command to generate a key. ''; type = types.path; apply = s: "<" + toString s; @@ -311,17 +311,17 @@ in enabled = mkEnableOption "GitLab integration"; canonical-upstream = mkOption { type = types.str; - description = "Canonical upstream."; + description = lib.mdDoc "Canonical upstream."; default = "gitlab.com"; }; repo-cache = mkOption { type = types.str; - description = "Repository cache directory."; + description = lib.mdDoc "Repository cache directory."; default = "./repo-cache"; }; "gitlab.com" = mkOption { type = with types; nullOr str; - description = "GitLab id and secret."; + description = lib.mdDoc "GitLab id and secret."; default = null; example = "GitLab:application id:secret"; }; @@ -330,17 +330,17 @@ in options."builds.sr.ht" = commonServiceSettings "builds" // { allow-free = mkEnableOption "nonpaying users to submit builds"; redis = mkOption { - description = "The Redis connection used for the Celery worker."; + description = lib.mdDoc "The Redis connection used for the Celery worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-buildsrht/redis.sock?virtual_host=2"; }; shell = mkOption { - description = '' + description = lib.mdDoc '' Scripts used to launch on SSH connection. - <literal>/usr/bin/master-shell</literal> on master, - <literal>/usr/bin/runner-shell</literal> on runner. + `/usr/bin/master-shell` on master, + `/usr/bin/runner-shell` on runner. If master and worker are on the same system - set to <literal>/usr/bin/runner-shell</literal>. + set to `/usr/bin/runner-shell`. ''; type = types.enum ["/usr/bin/master-shell" "/usr/bin/runner-shell"]; default = "/usr/bin/master-shell"; @@ -348,19 +348,19 @@ in }; options."builds.sr.ht::worker" = { bind-address = mkOption { - description = '' + description = lib.mdDoc '' HTTP bind address for serving local build information/monitoring. ''; type = types.str; default = "localhost:8080"; }; buildlogs = mkOption { - description = "Path to write build logs."; + description = lib.mdDoc "Path to write build logs."; type = types.str; default = "/var/log/sourcehut/buildsrht-worker"; }; name = mkOption { - description = '' + description = lib.mdDoc '' Listening address and listening port of the build runner (with HTTP port if not 80). ''; @@ -368,9 +368,9 @@ in default = "localhost:5020"; }; timeout = mkOption { - description = '' + description = lib.mdDoc '' Max build duration. - See <link xlink:href="https://golang.org/pkg/time/#ParseDuration"/>. + See <https://golang.org/pkg/time/#ParseDuration>. ''; type = types.str; default = "3m"; @@ -379,12 +379,12 @@ in options."git.sr.ht" = commonServiceSettings "git" // { outgoing-domain = mkOption { - description = "Outgoing domain."; + description = lib.mdDoc "Outgoing domain."; type = types.str; default = "https://git.localhost.localdomain"; }; post-update-script = mkOption { - description = '' + description = lib.mdDoc '' A post-update script which is installed in every git repo. This setting is propagated to newer and existing repositories. ''; @@ -393,7 +393,7 @@ in defaultText = "\${pkgs.sourcehut.gitsrht}/bin/gitsrht-update-hook"; }; repos = mkOption { - description = '' + description = lib.mdDoc '' Path to git repositories on disk. If changing the default, you must ensure that the gitsrht's user as read and write access to it. @@ -402,18 +402,18 @@ in default = "/var/lib/sourcehut/gitsrht/repos"; }; webhooks = mkOption { - description = "The Redis connection used for the webhooks worker."; + description = lib.mdDoc "The Redis connection used for the webhooks worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-gitsrht/redis.sock?virtual_host=1"; }; }; options."git.sr.ht::api" = { internal-ipnet = mkOption { - description = '' + description = lib.mdDoc '' Set of IP subnets which are permitted to utilize internal API authentication. This should be limited to the subnets from which your *.sr.ht services are running. - See <xref linkend="opt-services.sourcehut.listenAddress"/>. + See [](#opt-services.sourcehut.listenAddress). ''; type = with types; listOf str; default = [ "127.0.0.0/8" "::1/128" ]; @@ -422,7 +422,7 @@ in options."hg.sr.ht" = commonServiceSettings "hg" // { changegroup-script = mkOption { - description = '' + description = lib.mdDoc '' A changegroup script which is installed in every mercurial repo. This setting is propagated to newer and existing repositories. ''; @@ -431,7 +431,7 @@ in defaultText = "\${cfg.python}/bin/hgsrht-hook-changegroup"; }; repos = mkOption { - description = '' + description = lib.mdDoc '' Path to mercurial repositories on disk. If changing the default, you must ensure that the hgsrht's user as read and write access to it. @@ -444,18 +444,18 @@ in (defaults to where the hgsrht code is) ''; clone_bundle_threshold = mkOption { - description = ".hg/store size (in MB) past which the nightly job generates clone bundles."; + description = lib.mdDoc ".hg/store size (in MB) past which the nightly job generates clone bundles."; type = types.ints.unsigned; default = 50; }; hg_ssh = mkOption { - description = "Path to hg-ssh (if not in $PATH)."; + description = lib.mdDoc "Path to hg-ssh (if not in $PATH)."; type = types.str; default = "${pkgs.mercurial}/bin/hg-ssh"; defaultText = "\${pkgs.mercurial}/bin/hg-ssh"; }; webhooks = mkOption { - description = "The Redis connection used for the webhooks worker."; + description = lib.mdDoc "The Redis connection used for the webhooks worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-hgsrht/redis.sock?virtual_host=1"; }; @@ -467,29 +467,29 @@ in options."lists.sr.ht" = commonServiceSettings "lists" // { allow-new-lists = mkEnableOption "Allow creation of new lists."; notify-from = mkOption { - description = "Outgoing email for notifications generated by users."; + description = lib.mdDoc "Outgoing email for notifications generated by users."; type = types.str; default = "lists-notify@localhost.localdomain"; }; posting-domain = mkOption { - description = "Posting domain."; + description = lib.mdDoc "Posting domain."; type = types.str; default = "lists.localhost.localdomain"; }; redis = mkOption { - description = "The Redis connection used for the Celery worker."; + description = lib.mdDoc "The Redis connection used for the Celery worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-listssrht/redis.sock?virtual_host=2"; }; webhooks = mkOption { - description = "The Redis connection used for the webhooks worker."; + description = lib.mdDoc "The Redis connection used for the webhooks worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-listssrht/redis.sock?virtual_host=1"; }; }; options."lists.sr.ht::worker" = { reject-mimetypes = mkOption { - description = '' + description = lib.mdDoc '' Comma-delimited list of Content-Types to reject. Messages with Content-Types included in this list are rejected. Multipart messages are always supported, and each part is checked against this list. @@ -500,12 +500,12 @@ in default = ["text/html"]; }; reject-url = mkOption { - description = "Reject URL."; + description = lib.mdDoc "Reject URL."; type = types.str; default = "https://man.sr.ht/lists.sr.ht/etiquette.md"; }; sock = mkOption { - description = '' + description = lib.mdDoc '' Path for the lmtp daemon's unix socket. Direct incoming mail to this socket. Alternatively, specify IP:PORT and an SMTP server will be run instead. ''; @@ -513,7 +513,7 @@ in default = "/tmp/lists.sr.ht-lmtp.sock"; }; sock-group = mkOption { - description = '' + description = lib.mdDoc '' The lmtp daemon will make the unix socket group-read/write for users in this group. ''; @@ -529,13 +529,13 @@ in removeAttrs (commonServiceSettings "meta") ["oauth-client-id" "oauth-client-secret"] // { api-origin = mkOption { - description = "Origin URL for API, 100 more than web."; + 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)}''; }; webhooks = mkOption { - description = "The Redis connection used for the webhooks worker."; + description = lib.mdDoc "The Redis connection used for the webhooks worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-metasrht/redis.sock?virtual_host=1"; }; @@ -543,18 +543,18 @@ in }; options."meta.sr.ht::api" = { internal-ipnet = mkOption { - description = '' + description = lib.mdDoc '' Set of IP subnets which are permitted to utilize internal API authentication. This should be limited to the subnets from which your *.sr.ht services are running. - See <xref linkend="opt-services.sourcehut.listenAddress"/>. + See [](#opt-services.sourcehut.listenAddress). ''; type = with types; listOf str; default = [ "127.0.0.0/8" "::1/128" ]; }; }; options."meta.sr.ht::aliases" = mkOption { - description = "Aliases for the client IDs of commonly used OAuth clients."; + description = lib.mdDoc "Aliases for the client IDs of commonly used OAuth clients."; type = with types; attrsOf int; default = {}; example = { "git.sr.ht" = 12345; }; @@ -572,12 +572,12 @@ in options."meta.sr.ht::settings" = { registration = mkEnableOption "public registration"; onboarding-redirect = mkOption { - description = "Where to redirect new users upon registration."; + description = lib.mdDoc "Where to redirect new users upon registration."; type = types.str; default = "https://meta.localhost.localdomain"; }; user-invites = mkOption { - description = '' + description = lib.mdDoc '' How many invites each user is issued upon registration (only applicable if open registration is disabled). ''; @@ -588,7 +588,7 @@ in options."pages.sr.ht" = commonServiceSettings "pages" // { gemini-certs = mkOption { - description = '' + description = lib.mdDoc '' An absolute file path (which should be outside the Nix-store) to Gemini certificates. ''; @@ -596,7 +596,7 @@ in default = null; }; max-site-size = mkOption { - description = "Maximum size of any given site (post-gunzip), in MiB."; + description = lib.mdDoc "Maximum size of any given site (post-gunzip), in MiB."; type = types.int; default = 1024; }; @@ -611,11 +611,11 @@ in }; options."pages.sr.ht::api" = { internal-ipnet = mkOption { - description = '' + description = lib.mdDoc '' Set of IP subnets which are permitted to utilize internal API authentication. This should be limited to the subnets from which your *.sr.ht services are running. - See <xref linkend="opt-services.sourcehut.listenAddress"/>. + See [](#opt-services.sourcehut.listenAddress). ''; type = with types; listOf str; default = [ "127.0.0.0/8" "::1/128" ]; @@ -627,24 +627,24 @@ in options."todo.sr.ht" = commonServiceSettings "todo" // { notify-from = mkOption { - description = "Outgoing email for notifications generated by users."; + description = lib.mdDoc "Outgoing email for notifications generated by users."; type = types.str; default = "todo-notify@localhost.localdomain"; }; webhooks = mkOption { - description = "The Redis connection used for the webhooks worker."; + description = lib.mdDoc "The Redis connection used for the webhooks worker."; type = types.str; default = "redis+socket:///run/redis-sourcehut-todosrht/redis.sock?virtual_host=1"; }; }; options."todo.sr.ht::mail" = { posting-domain = mkOption { - description = "Posting domain."; + description = lib.mdDoc "Posting domain."; type = types.str; default = "todo.localhost.localdomain"; }; sock = mkOption { - description = '' + description = lib.mdDoc '' Path for the lmtp daemon's unix socket. Direct incoming mail to this socket. Alternatively, specify IP:PORT and an SMTP server will be run instead. ''; @@ -652,7 +652,7 @@ in default = "/tmp/todo.sr.ht-lmtp.sock"; }; sock-group = mkOption { - description = '' + description = lib.mdDoc '' The lmtp daemon will make the unix socket group-read/write for users in this group. ''; @@ -662,7 +662,7 @@ in }; }; default = { }; - description = '' + description = lib.mdDoc '' The configuration for the sourcehut network. ''; }; @@ -698,7 +698,7 @@ in nixos.unstable.x86_64 = image_from_nixpkgs; } )''; - description = '' + description = lib.mdDoc '' Images for builds.sr.ht. Each package should be distro.release.arch and point to a /nix/store/package/root.img.qcow2. ''; }; @@ -710,12 +710,12 @@ in default = pkgs.git; defaultText = literalExpression "pkgs.git"; example = literalExpression "pkgs.gitFull"; - description = '' + description = lib.mdDoc '' Git package for git.sr.ht. This can help silence collisions. ''; }; fcgiwrap.preforkProcess = mkOption { - description = "Number of fcgiwrap processes to prefork."; + description = lib.mdDoc "Number of fcgiwrap processes to prefork."; type = types.int; default = 4; }; @@ -726,14 +726,14 @@ in type = types.package; default = pkgs.mercurial; defaultText = literalExpression "pkgs.mercurial"; - description = '' + description = lib.mdDoc '' Mercurial package for hg.sr.ht. This can help silence collisions. ''; }; cloneBundles = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Generate clonebundles (which require more disk space but dramatically speed up cloning large repositories). ''; }; @@ -744,12 +744,12 @@ in extraArgs = mkOption { type = with types; listOf str; default = [ "--loglevel DEBUG" "--pool eventlet" "--without-heartbeat" ]; - description = "Extra arguments passed to the Celery responsible for processing mails."; + description = lib.mdDoc "Extra arguments passed to the Celery responsible for processing mails."; }; celeryConfig = mkOption { type = types.lines; default = ""; - description = "Content of the <literal>celeryconfig.py</literal> used by the Celery of <literal>listssrht-process</literal>."; + description = lib.mdDoc "Content of the `celeryconfig.py` used by the Celery of `listssrht-process`."; }; }; }; diff --git a/nixos/modules/services/misc/sourcehut/service.nix b/nixos/modules/services/misc/sourcehut/service.nix index 4ecc7a72669..243a9cef590 100644 --- a/nixos/modules/services/misc/sourcehut/service.nix +++ b/nixos/modules/services/misc/sourcehut/service.nix @@ -122,7 +122,7 @@ in user = mkOption { type = types.str; default = srvsrht; - description = '' + description = lib.mdDoc '' User for ${srv}.sr.ht. ''; }; @@ -130,7 +130,7 @@ in group = mkOption { type = types.str; default = srvsrht; - description = '' + description = lib.mdDoc '' Group for ${srv}.sr.ht. Membership grants access to the Git/Mercurial repositories by default, but not to the config.ini file (where secrets are). @@ -140,7 +140,7 @@ in port = mkOption { type = types.port; default = port; - description = '' + description = lib.mdDoc '' Port on which the "${srv}" backend should listen. ''; }; @@ -150,7 +150,7 @@ in type = types.str; default = "unix:///run/redis-sourcehut-${srvsrht}/redis.sock?db=0"; example = "redis://shared.wireguard:6379/0"; - description = '' + description = lib.mdDoc '' The redis host URL. This is used for caching and temporary storage, and must be shared between nodes (e.g. git1.sr.ht and git2.sr.ht), but need not be shared between services. It may be shared between services, however, with no @@ -163,9 +163,9 @@ in database = mkOption { type = types.str; default = "${srv}.sr.ht"; - description = '' + description = lib.mdDoc '' PostgreSQL database name for the ${srv}.sr.ht service, - used if <xref linkend="opt-services.sourcehut.postgresql.enable"/> is <literal>true</literal>. + used if [](#opt-services.sourcehut.postgresql.enable) is `true`. ''; }; }; @@ -174,7 +174,7 @@ in extraArgs = mkOption { type = with types; listOf str; default = ["--timeout 120" "--workers 1" "--log-level=info"]; - description = "Extra arguments passed to Gunicorn."; + description = lib.mdDoc "Extra arguments passed to Gunicorn."; }; }; } // optionalAttrs webhooks { @@ -182,12 +182,12 @@ in extraArgs = mkOption { type = with types; listOf str; default = ["--loglevel DEBUG" "--pool eventlet" "--without-heartbeat"]; - description = "Extra arguments passed to the Celery responsible for webhooks."; + description = lib.mdDoc "Extra arguments passed to the Celery responsible for webhooks."; }; celeryConfig = mkOption { type = types.lines; default = ""; - description = "Content of the <literal>celeryconfig.py</literal> used by the Celery responsible for webhooks."; + description = lib.mdDoc "Content of the `celeryconfig.py` used by the Celery responsible for webhooks."; }; }; }; diff --git a/nixos/modules/services/misc/taskserver/default.nix b/nixos/modules/services/misc/taskserver/default.nix index c8a2c21b9ec..ad4ab93a872 100644 --- a/nixos/modules/services/misc/taskserver/default.nix +++ b/nixos/modules/services/misc/taskserver/default.nix @@ -227,8 +227,8 @@ in { queueSize = mkOption { type = types.int; default = 10; - description = '' - Size of the connection backlog, see <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + description = lib.mdDoc '' + Size of the connection backlog, see {manpage}`listen(2)`. ''; }; @@ -321,16 +321,16 @@ in { config = mkOption { type = types.attrs; example.client.cert = "/tmp/debugging.cert"; - description = '' + description = lib.mdDoc '' Configuration options to pass to Taskserver. The options here are the same as described in - <citerefentry><refentrytitle>taskdrc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, but with one difference: + {manpage}`taskdrc(5)`, but with one difference: - The <literal>server</literal> option is - <literal>server.listen</literal> here, because the - <literal>server</literal> option would collide with other options - like <literal>server.cert</literal> and we would run in a type error + The `server` option is + `server.listen` here, because the + `server` option would collide with other options + like `server.cert` and we would run in a type error (attribute set versus string). Nix types like integers or booleans are automatically converted to diff --git a/nixos/modules/services/monitoring/nagios.nix b/nixos/modules/services/monitoring/nagios.nix index a17797f682f..a45d0c0e070 100644 --- a/nixos/modules/services/monitoring/nagios.nix +++ b/nixos/modules/services/monitoring/nagios.nix @@ -125,14 +125,14 @@ in debug_file = "/var/log/nagios/debug.log"; }; default = {}; - description = "Configuration to add to /etc/nagios.cfg"; + description = lib.mdDoc "Configuration to add to /etc/nagios.cfg"; }; validateConfig = mkOption { type = types.bool; default = pkgs.stdenv.hostPlatform == pkgs.stdenv.buildPlatform; defaultText = literalExpression "pkgs.stdenv.hostPlatform == pkgs.stdenv.buildPlatform"; - description = "if true, the syntax of the nagios configuration file is checked at build time"; + description = lib.mdDoc "if true, the syntax of the nagios configuration file is checked at build time"; }; cgiConfigFile = mkOption { @@ -164,9 +164,9 @@ in sslServerKey = "/var/lib/acme/example.org/key.pem"; } ''; - description = '' - Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>. - See <xref linkend="opt-services.httpd.virtualHosts"/> for further information. + description = lib.mdDoc '' + Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters.nix b/nixos/modules/services/monitoring/prometheus/exporters.nix index 41302d6d3ce..47c30a0f24b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters.nix @@ -84,28 +84,28 @@ let port = mkOption { type = types.port; default = port; - description = '' + description = lib.mdDoc '' Port to listen on. ''; }; listenAddress = mkOption { type = types.str; default = "0.0.0.0"; - description = '' + description = lib.mdDoc '' Address to listen on. ''; }; extraFlags = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Extra commandline options to pass to the ${name} exporter. ''; }; openFirewall = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Open port in firewall for incoming connections. ''; }; @@ -124,14 +124,14 @@ let user = mkOption { type = types.str; default = "${name}-exporter"; - description = '' + description = lib.mdDoc '' User name under which the ${name} exporter shall be run. ''; }; group = mkOption { type = types.str; default = "${name}-exporter"; - description = '' + description = lib.mdDoc '' Group under which the ${name} exporter shall be run. ''; }; @@ -227,7 +227,7 @@ in type = types.submodule { options = (mkSubModules); }; - description = "Prometheus exporter configuration"; + description = lib.mdDoc "Prometheus exporter configuration"; default = {}; example = literalExpression '' { diff --git a/nixos/modules/services/monitoring/prometheus/exporters/apcupsd.nix b/nixos/modules/services/monitoring/prometheus/exporters/apcupsd.nix index 57c35a742c5..a8a9f84ea8e 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/apcupsd.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/apcupsd.nix @@ -11,7 +11,7 @@ in apcupsdAddress = mkOption { type = types.str; default = ":3551"; - description = '' + description = lib.mdDoc '' Address of the apcupsd Network Information Server (NIS). ''; }; @@ -19,7 +19,7 @@ in apcupsdNetwork = mkOption { type = types.enum ["tcp" "tcp4" "tcp6"]; default = "tcp"; - description = '' + description = lib.mdDoc '' Network of the apcupsd Network Information Server (NIS): one of "tcp", "tcp4", or "tcp6". ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/artifactory.nix b/nixos/modules/services/monitoring/prometheus/exporters/artifactory.nix index 2adcecc728b..bc67fe59b3b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/artifactory.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/artifactory.nix @@ -11,14 +11,14 @@ in scrapeUri = mkOption { type = types.str; default = "http://localhost:8081/artifactory"; - description = '' + description = lib.mdDoc '' URI on which to scrape JFrog Artifactory. ''; }; artiUsername = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Username for authentication against JFrog Artifactory API. ''; }; @@ -26,7 +26,7 @@ in artiPassword = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' Password for authentication against JFrog Artifactory API. One of the password or access token needs to be set. ''; @@ -35,7 +35,7 @@ in artiAccessToken = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' Access token for authentication against JFrog Artifactory API. One of the password or access token needs to be set. ''; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/bind.nix b/nixos/modules/services/monitoring/prometheus/exporters/bind.nix index 16c2920751d..bd2003f0650 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/bind.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/bind.nix @@ -11,28 +11,28 @@ in bindURI = mkOption { type = types.str; default = "http://localhost:8053/"; - description = '' + description = lib.mdDoc '' HTTP XML API address of an Bind server. ''; }; bindTimeout = mkOption { type = types.str; default = "10s"; - description = '' + description = lib.mdDoc '' Timeout for trying to get stats from Bind. ''; }; bindVersion = mkOption { type = types.enum [ "xml.v2" "xml.v3" "auto" ]; default = "auto"; - description = '' + description = lib.mdDoc '' BIND statistics version. Can be detected automatically. ''; }; bindGroups = mkOption { type = types.listOf (types.enum [ "server" "view" "tasks" ]); default = [ "server" "view" ]; - description = '' + description = lib.mdDoc '' List of statistics to collect. Available: [server, view, tasks] ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/bird.nix b/nixos/modules/services/monitoring/prometheus/exporters/bird.nix index 5fda4c980eb..5f6c36f4c56 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/bird.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/bird.nix @@ -11,21 +11,21 @@ in birdVersion = mkOption { type = types.enum [ 1 2 ]; default = 2; - description = '' + description = lib.mdDoc '' Specifies whether BIRD1 or BIRD2 is in use. ''; }; birdSocket = mkOption { type = types.path; default = "/run/bird/bird.ctl"; - description = '' + description = lib.mdDoc '' Path to BIRD2 (or BIRD1 v4) socket. ''; }; newMetricFormat = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable the new more-generic metric format. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/bitcoin.nix b/nixos/modules/services/monitoring/prometheus/exporters/bitcoin.nix index 43721f70b49..330d5412644 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/bitcoin.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/bitcoin.nix @@ -11,14 +11,14 @@ in rpcUser = mkOption { type = types.str; default = "bitcoinrpc"; - description = '' + description = lib.mdDoc '' RPC user name. ''; }; rpcPasswordFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' File containing RPC password. ''; }; @@ -26,7 +26,7 @@ in rpcScheme = mkOption { type = types.enum [ "http" "https" ]; default = "http"; - description = '' + description = lib.mdDoc '' Whether to connect to bitcoind over http or https. ''; }; @@ -34,7 +34,7 @@ in rpcHost = mkOption { type = types.str; default = "localhost"; - description = '' + description = lib.mdDoc '' RPC host. ''; }; @@ -42,7 +42,7 @@ in rpcPort = mkOption { type = types.port; default = 8332; - description = '' + description = lib.mdDoc '' RPC port number. ''; }; @@ -50,7 +50,7 @@ in refreshSeconds = mkOption { type = types.ints.unsigned; default = 300; - description = '' + description = lib.mdDoc '' How often to ask bitcoind for metrics. ''; }; @@ -58,7 +58,7 @@ in extraEnv = mkOption { type = types.attrsOf types.str; default = {}; - description = '' + description = lib.mdDoc '' Extra environment variables for the exporter. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/blackbox.nix b/nixos/modules/services/monitoring/prometheus/exporters/blackbox.nix index fe8d905da3f..66eaed51d2e 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/blackbox.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/blackbox.nix @@ -35,14 +35,14 @@ in { extraOpts = { configFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to configuration file. ''; }; enableConfigCheck = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to run a correctness check for the configuration file. This depends on the configuration file residing in the nix-store. Paths passed as string will be copied to the store. diff --git a/nixos/modules/services/monitoring/prometheus/exporters/buildkite-agent.nix b/nixos/modules/services/monitoring/prometheus/exporters/buildkite-agent.nix index e9be39608fc..0515b72b13f 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/buildkite-agent.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/buildkite-agent.nix @@ -11,7 +11,7 @@ in tokenPath = mkOption { type = types.nullOr types.path; apply = final: if final == null then null else toString final; - description = '' + description = lib.mdDoc '' The token from your Buildkite "Agents" page. A run-time path to the token file, which is supposed to be provisioned @@ -22,14 +22,14 @@ in type = types.str; default = "30s"; example = "1min"; - description = '' + description = lib.mdDoc '' How often to update metrics. ''; }; endpoint = mkOption { type = types.str; default = "https://agent.buildkite.com/v3"; - description = '' + description = lib.mdDoc '' The Buildkite Agent API endpoint. ''; }; @@ -37,7 +37,7 @@ in type = with types; nullOr (listOf str); default = null; example = literalExpression ''[ "my-queue1" "my-queue2" ]''; - description = '' + description = lib.mdDoc '' Which specific queues to process. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/collectd.nix b/nixos/modules/services/monitoring/prometheus/exporters/collectd.nix index a7f4d3e096f..eab1f9e7b4d 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/collectd.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/collectd.nix @@ -14,19 +14,19 @@ in authFile = mkOption { default = null; type = types.nullOr types.path; - description = "File mapping user names to pre-shared keys (passwords)."; + description = lib.mdDoc "File mapping user names to pre-shared keys (passwords)."; }; port = mkOption { type = types.int; default = 25826; - description = "Network address on which to accept collectd binary network packets."; + description = lib.mdDoc "Network address on which to accept collectd binary network packets."; }; listenAddress = mkOption { type = types.str; default = "0.0.0.0"; - description = '' + description = lib.mdDoc '' Address to listen on for binary network packets. ''; }; @@ -34,7 +34,7 @@ in securityLevel = mkOption { type = types.enum ["None" "Sign" "Encrypt"]; default = "None"; - description = '' + description = lib.mdDoc '' Minimum required security level for accepted packets. ''; }; @@ -44,7 +44,7 @@ in type = types.enum [ "logfmt" "json" ]; default = "logfmt"; example = "json"; - description = '' + description = lib.mdDoc '' Set the log format. ''; }; @@ -52,7 +52,7 @@ in logLevel = mkOption { type = types.enum ["debug" "info" "warn" "error" "fatal"]; default = "info"; - description = '' + description = lib.mdDoc '' Only log messages with the given severity or above. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/dmarc.nix b/nixos/modules/services/monitoring/prometheus/exporters/dmarc.nix index 25950e1ece9..437cece588a 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/dmarc.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/dmarc.nix @@ -24,28 +24,28 @@ in { host = mkOption { type = types.str; default = "localhost"; - description = '' + description = lib.mdDoc '' Hostname of IMAP server to connect to. ''; }; port = mkOption { type = types.port; default = 993; - description = '' + description = lib.mdDoc '' Port of the IMAP server to connect to. ''; }; username = mkOption { type = types.str; example = "postmaster@example.org"; - description = '' + description = lib.mdDoc '' Login username for the IMAP connection. ''; }; passwordFile = mkOption { type = types.str; example = "/run/secrets/dovecot_pw"; - description = '' + description = lib.mdDoc '' File containing the login password for the IMAP connection. ''; }; @@ -54,21 +54,21 @@ in { inbox = mkOption { type = types.str; default = "INBOX"; - description = '' + description = lib.mdDoc '' IMAP mailbox that is checked for incoming DMARC aggregate reports ''; }; done = mkOption { type = types.str; default = "Archive"; - description = '' + description = lib.mdDoc '' IMAP mailbox that successfully processed reports are moved to. ''; }; error = mkOption { type = types.str; default = "Invalid"; - description = '' + description = lib.mdDoc '' IMAP mailbox that emails are moved to that could not be processed. ''; }; @@ -76,7 +76,7 @@ in { pollIntervalSeconds = mkOption { type = types.ints.unsigned; default = 60; - description = '' + description = lib.mdDoc '' How often to poll the IMAP server in seconds. ''; }; @@ -84,7 +84,7 @@ in { type = types.ints.unsigned; default = 604800; defaultText = "7 days (in seconds)"; - description = '' + description = lib.mdDoc '' How long individual report IDs will be remembered to avoid counting double delivered reports twice. ''; @@ -92,8 +92,8 @@ in { debug = mkOption { type = types.bool; default = false; - description = '' - Whether to declare enable <literal>--debug</literal>. + description = lib.mdDoc '' + Whether to declare enable `--debug`. ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/dnsmasq.nix b/nixos/modules/services/monitoring/prometheus/exporters/dnsmasq.nix index 68afba21d64..ece42a34cb0 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/dnsmasq.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/dnsmasq.nix @@ -11,7 +11,7 @@ in dnsmasqListenAddress = mkOption { type = types.str; default = "localhost:53"; - description = '' + description = lib.mdDoc '' Address on which dnsmasq listens. ''; }; @@ -19,8 +19,8 @@ in type = types.path; default = "/var/lib/misc/dnsmasq.leases"; example = "/var/lib/dnsmasq/dnsmasq.leases"; - description = '' - Path to the <literal>dnsmasq.leases</literal> file. + description = lib.mdDoc '' + Path to the `dnsmasq.leases` file. ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix b/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix index 4e7aae0b34b..d86b750ba5f 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/dovecot.nix @@ -11,7 +11,7 @@ in telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; @@ -67,7 +67,7 @@ in type = types.listOf types.str; default = [ "user" ]; example = [ "user" "global" ]; - description = '' + description = lib.mdDoc '' Stats scopes to query. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/fastly.nix b/nixos/modules/services/monitoring/prometheus/exporters/fastly.nix index 55a61c4949e..182a1131c05 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/fastly.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/fastly.nix @@ -12,9 +12,9 @@ in configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Path to a fastly-exporter configuration file. - Example one can be generated with <literal>fastly-exporter --config-file-example</literal>. + Example one can be generated with `fastly-exporter --config-file-example`. ''; example = "./fastly-exporter-config.txt"; }; @@ -22,7 +22,7 @@ in tokenPath = mkOption { type = types.nullOr types.path; apply = final: if final == null then null else toString final; - description = '' + description = lib.mdDoc '' A run-time path to the token file, which is supposed to be provisioned outside of Nix store. ''; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/flow.nix b/nixos/modules/services/monitoring/prometheus/exporters/flow.nix index b85e5461f21..81099aaf170 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/flow.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/flow.nix @@ -10,19 +10,19 @@ in { brokers = mkOption { type = types.listOf types.str; example = literalExpression ''[ "kafka.example.org:19092" ]''; - description = "List of Kafka brokers to connect to."; + description = lib.mdDoc "List of Kafka brokers to connect to."; }; asn = mkOption { type = types.ints.positive; example = 65542; - description = "The ASN being monitored."; + description = lib.mdDoc "The ASN being monitored."; }; partitions = mkOption { type = types.listOf types.int; default = []; - description = '' + description = lib.mdDoc '' The number of the partitions to consume, none means all. ''; }; @@ -30,7 +30,7 @@ in { topic = mkOption { type = types.str; example = "pmacct.acct"; - description = "The Kafka topic to consume from."; + description = lib.mdDoc "The Kafka topic to consume from."; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/fritzbox.nix b/nixos/modules/services/monitoring/prometheus/exporters/fritzbox.nix index 9526597b8c9..dc53d21406f 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/fritzbox.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/fritzbox.nix @@ -11,7 +11,7 @@ in gatewayAddress = mkOption { type = types.str; default = "fritz.box"; - description = '' + description = lib.mdDoc '' The hostname or IP of the FRITZ!Box. ''; }; @@ -19,7 +19,7 @@ in gatewayPort = mkOption { type = types.int; default = 49000; - description = '' + description = lib.mdDoc '' The port of the FRITZ!Box UPnP service. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/influxdb.nix b/nixos/modules/services/monitoring/prometheus/exporters/influxdb.nix index ba45173e946..61c0c08d225 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/influxdb.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/influxdb.nix @@ -12,13 +12,13 @@ in type = types.str; default = "5m"; example = "10m"; - description = "How long a sample is valid for"; + description = lib.mdDoc "How long a sample is valid for"; }; udpBindAddress = mkOption { type = types.str; default = ":9122"; example = "192.0.2.1:9122"; - description = "Address on which to listen for udp packets"; + description = lib.mdDoc "Address on which to listen for udp packets"; }; }; serviceOpts = { diff --git a/nixos/modules/services/monitoring/prometheus/exporters/jitsi.nix b/nixos/modules/services/monitoring/prometheus/exporters/jitsi.nix index c93a8f98e55..02460271860 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/jitsi.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/jitsi.nix @@ -11,7 +11,7 @@ in url = mkOption { type = types.str; default = "http://localhost:8080/colibri/stats"; - description = '' + description = lib.mdDoc '' Jitsi Videobridge metrics URL to monitor. This is usually /colibri/stats on port 8080 of the jitsi videobridge host. ''; @@ -20,7 +20,7 @@ in type = types.str; default = "30s"; example = "1min"; - description = '' + description = lib.mdDoc '' How often to scrape new data ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/json.nix b/nixos/modules/services/monitoring/prometheus/exporters/json.nix index 1800da69a25..473f3a7e47e 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/json.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/json.nix @@ -10,7 +10,7 @@ in extraOpts = { configFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to configuration file. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/kea.nix b/nixos/modules/services/monitoring/prometheus/exporters/kea.nix index e0ee90d9b97..0682f9da400 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/kea.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/kea.nix @@ -19,7 +19,7 @@ in { "/run/kea/kea-dhcp6.socket" ] ''; - description = '' + description = lib.mdDoc '' Paths to kea control sockets ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/knot.nix b/nixos/modules/services/monitoring/prometheus/exporters/knot.nix index e5ba6c4d6cd..2df0ab93bde 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/knot.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/knot.nix @@ -19,15 +19,15 @@ in { knotSocketPath = mkOption { type = types.str; default = "/run/knot/knot.sock"; - description = '' - Socket path of <citerefentry><refentrytitle>knotd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + description = lib.mdDoc '' + Socket path of {manpage}`knotd(8)`. ''; }; knotSocketTimeout = mkOption { type = types.int; default = 2000; - description = '' + description = lib.mdDoc '' Timeout in seconds. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/lnd.nix b/nixos/modules/services/monitoring/prometheus/exporters/lnd.nix index 35f97202057..9f914b1dc14 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/lnd.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/lnd.nix @@ -11,21 +11,21 @@ in lndHost = mkOption { type = types.str; default = "localhost:10009"; - description = '' + description = lib.mdDoc '' lnd instance gRPC address:port. ''; }; lndTlsPath = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to lnd TLS certificate. ''; }; lndMacaroonDir = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to lnd macaroons. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/mail.nix b/nixos/modules/services/monitoring/prometheus/exporters/mail.nix index e2dada4c119..205188538a2 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/mail.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/mail.nix @@ -22,41 +22,41 @@ let serverOptions.options = { name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Value for label 'configname' which will be added to all metrics. ''; }; server = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Hostname of the server that should be probed. ''; }; port = mkOption { type = types.int; example = 587; - description = '' + description = lib.mdDoc '' Port to use for SMTP. ''; }; from = mkOption { type = types.str; example = "exporteruser@domain.tld"; - description = '' + description = lib.mdDoc '' Content of 'From' Header for probing mails. ''; }; to = mkOption { type = types.str; example = "exporteruser@domain.tld"; - description = '' + description = lib.mdDoc '' Content of 'To' Header for probing mails. ''; }; detectionDir = mkOption { type = types.path; example = "/var/spool/mail/exporteruser/new"; - description = '' + description = lib.mdDoc '' Directory in which new mails for the exporter user are placed. Note that this needs to exist when the exporter starts. ''; @@ -65,14 +65,14 @@ let type = types.nullOr types.str; default = null; example = "exporteruser@domain.tld"; - description = '' + description = lib.mdDoc '' Username to use for SMTP authentication. ''; }; passphrase = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Password to use for SMTP authentication. ''; }; @@ -82,20 +82,20 @@ let monitoringInterval = mkOption { type = types.str; example = "10s"; - description = '' + description = lib.mdDoc '' Time interval between two probe attempts. ''; }; mailCheckTimeout = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Timeout until mails are considered "didn't make it". ''; }; disableFileDeletion = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Disables the exporter's function to delete probing mails. ''; }; @@ -141,28 +141,28 @@ in environmentFile = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' File containing env-vars to be substituted into the exporter's config. ''; }; configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Specify the mailexporter configuration file to use. ''; }; configuration = mkOption { type = types.nullOr (types.submodule exporterOptions); default = null; - description = '' + description = lib.mdDoc '' Specify the mailexporter configuration file to use. ''; }; telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/mikrotik.nix b/nixos/modules/services/monitoring/prometheus/exporters/mikrotik.nix index 8f9536b702a..54dab4b5581 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/mikrotik.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/mikrotik.nix @@ -11,9 +11,9 @@ in configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Path to a mikrotik exporter configuration file. Mutually exclusive with - <option>configuration</option> option. + {option}`configuration` option. ''; example = literalExpression "./mikrotik.yml"; }; @@ -21,11 +21,11 @@ in configuration = mkOption { type = types.nullOr types.attrs; default = null; - description = '' + description = lib.mdDoc '' Mikrotik exporter configuration as nix attribute set. Mutually exclusive with - <option>configFile</option> option. + {option}`configFile` option. - See <link xlink:href="https://github.com/nshttpd/mikrotik-exporter/blob/master/README.md"/> + See <https://github.com/nshttpd/mikrotik-exporter/blob/master/README.md> for the description of the configuration file format. ''; example = literalExpression '' diff --git a/nixos/modules/services/monitoring/prometheus/exporters/minio.nix b/nixos/modules/services/monitoring/prometheus/exporters/minio.nix index d6dd62f871b..82cc3fc314f 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/minio.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/minio.nix @@ -11,7 +11,7 @@ in minioAddress = mkOption { type = types.str; example = "https://10.0.0.1:9000"; - description = '' + description = lib.mdDoc '' The URL of the minio server. Use HTTPS if Minio accepts secure connections only. By default this connects to the local minio server if enabled. @@ -21,28 +21,28 @@ in minioAccessKey = mkOption { type = types.str; example = "yourMinioAccessKey"; - description = '' + description = lib.mdDoc '' The value of the Minio access key. It is required in order to connect to the server. By default this uses the one from the local minio server if enabled - and <literal>config.services.minio.accessKey</literal>. + and `config.services.minio.accessKey`. ''; }; minioAccessSecret = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The value of the Minio access secret. It is required in order to connect to the server. By default this uses the one from the local minio server if enabled - and <literal>config.services.minio.secretKey</literal>. + and `config.services.minio.secretKey`. ''; }; minioBucketStats = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Collect statistics about the buckets and files in buckets. It requires more computation, use it carefully in case of large buckets.. ''; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/modemmanager.nix b/nixos/modules/services/monitoring/prometheus/exporters/modemmanager.nix index afd03f6c270..222ea3e5384 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/modemmanager.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/modemmanager.nix @@ -11,7 +11,7 @@ in refreshRate = mkOption { type = types.str; default = "5s"; - description = '' + description = lib.mdDoc '' How frequently ModemManager will refresh the extended signal quality information for each modem. The duration should be specified in seconds ("5s"), minutes ("1m"), or hours ("1h"). diff --git a/nixos/modules/services/monitoring/prometheus/exporters/nextcloud.nix b/nixos/modules/services/monitoring/prometheus/exporters/nextcloud.nix index ce7125bf5a8..7808c8861a7 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/nextcloud.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/nextcloud.nix @@ -11,16 +11,16 @@ in url = mkOption { type = types.str; example = "https://domain.tld"; - description = '' + description = lib.mdDoc '' URL to the Nextcloud serverinfo page. Adding the path to the serverinfo API is optional, it defaults - to <literal>/ocs/v2.php/apps/serverinfo/api/v1/info</literal>. + to `/ocs/v2.php/apps/serverinfo/api/v1/info`. ''; }; username = mkOption { type = types.str; default = "nextcloud-exporter"; - description = '' + description = lib.mdDoc '' Username for connecting to Nextcloud. Note that this account needs to have admin privileges in Nextcloud. ''; @@ -28,7 +28,7 @@ in passwordFile = mkOption { type = types.path; example = "/path/to/password-file"; - description = '' + description = lib.mdDoc '' File containing the password for connecting to Nextcloud. Make sure that this file is readable by the exporter user. ''; @@ -36,7 +36,7 @@ in timeout = mkOption { type = types.str; default = "5s"; - description = '' + description = lib.mdDoc '' Timeout for getting server info document. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/nginx.nix b/nixos/modules/services/monitoring/prometheus/exporters/nginx.nix index 6f69f5919d1..3158e71f046 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/nginx.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/nginx.nix @@ -11,7 +11,7 @@ in scrapeUri = mkOption { type = types.str; default = "http://localhost/nginx_status"; - description = '' + description = lib.mdDoc '' Address to access the nginx status page. Can be enabled with services.nginx.statusPage = true. ''; @@ -19,14 +19,14 @@ in telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; sslVerify = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to perform certificate verification for https. ''; }; @@ -37,7 +37,7 @@ in "label1=value1" "label2=value2" ]; - description = '' + description = lib.mdDoc '' A list of constant labels that will be used in every metric. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/nginxlog.nix b/nixos/modules/services/monitoring/prometheus/exporters/nginxlog.nix index 8c1f552d58a..9967d3647e0 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/nginxlog.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/nginxlog.nix @@ -24,7 +24,7 @@ in { metricsEndpoint = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/node.nix b/nixos/modules/services/monitoring/prometheus/exporters/node.nix index 417920402f3..ae69c29d0a5 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/node.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/node.nix @@ -12,7 +12,7 @@ in type = types.listOf types.str; default = []; example = [ "systemd" ]; - description = '' + description = lib.mdDoc '' Collectors to enable. The collectors listed here are enabled in addition to the default ones. ''; }; @@ -20,7 +20,7 @@ in type = types.listOf types.str; default = []; example = [ "timex" ]; - description = '' + description = lib.mdDoc '' Collectors to disable which are enabled by default. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix b/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix index 888611ee6fa..59fcedef9dd 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/openldap.nix @@ -40,7 +40,7 @@ in { metricsPath = mkOption { default = "/metrics"; type = types.str; - description = '' + description = lib.mdDoc '' URL path where metrics should be exposed. ''; }; @@ -48,7 +48,7 @@ in { default = "30s"; type = types.str; example = "1m"; - description = '' + description = lib.mdDoc '' Scrape interval of the exporter. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/openvpn.nix b/nixos/modules/services/monitoring/prometheus/exporters/openvpn.nix index a97a753ebc3..5b54dad9980 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/openvpn.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/openvpn.nix @@ -9,15 +9,15 @@ in { extraOpts = { statusPaths = mkOption { type = types.listOf types.str; - description = '' + description = lib.mdDoc '' Paths to OpenVPN status files. Please configure the OpenVPN option - <literal>status</literal> accordingly. + `status` accordingly. ''; }; telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/pihole.nix b/nixos/modules/services/monitoring/prometheus/exporters/pihole.nix index 4bc27ebc32f..537d72e85c8 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/pihole.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/pihole.nix @@ -12,7 +12,7 @@ in type = types.str; default = ""; example = "580a770cb40511eb85290242ac130003580a770cb40511eb85290242ac130003"; - description = '' + description = lib.mdDoc '' pi-hole API token which can be used instead of a password ''; }; @@ -20,7 +20,7 @@ in type = types.str; default = "10s"; example = "30s"; - description = '' + description = lib.mdDoc '' How often to scrape new data ''; }; @@ -28,7 +28,7 @@ in type = types.str; default = ""; example = "password"; - description = '' + description = lib.mdDoc '' The password to login into pihole. An api token can be used instead. ''; }; @@ -36,7 +36,7 @@ in type = types.str; default = "pihole"; example = "127.0.0.1"; - description = '' + description = lib.mdDoc '' Hostname or address where to find the pihole webinterface ''; }; @@ -44,7 +44,7 @@ in type = types.port; default = 80; example = 443; - description = '' + description = lib.mdDoc '' The port pihole webinterface is reachable on ''; }; @@ -52,7 +52,7 @@ in type = types.enum [ "http" "https" ]; default = "http"; example = "https"; - description = '' + description = lib.mdDoc '' The protocol which is used to connect to pihole ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix b/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix index 53509b7a385..9f402b12311 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/postfix.nix @@ -10,17 +10,17 @@ in extraOpts = { group = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Group under which the postfix exporter shall be run. It should match the group that is allowed to access the - <literal>showq</literal> socket in the <literal>queue/public/</literal> directory. - Defaults to <literal>services.postfix.setgidGroup</literal> when postfix is enabled. + `showq` socket in the `queue/public/` directory. + Defaults to `services.postfix.setgidGroup` when postfix is enabled. ''; }; telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; @@ -28,7 +28,7 @@ in type = types.path; default = "/var/log/postfix_exporter_input.log"; example = "/var/log/mail.log"; - description = '' + description = lib.mdDoc '' Path where Postfix writes log entries. This file will be truncated by this exporter! ''; @@ -37,7 +37,7 @@ in type = types.path; default = "/var/lib/postfix/queue/public/showq"; example = "/var/spool/postfix/public/showq"; - description = '' + description = lib.mdDoc '' Path where Postfix places its showq socket. ''; }; @@ -45,29 +45,29 @@ in enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable reading metrics from the systemd journal instead of from a logfile ''; }; unit = mkOption { type = types.str; default = "postfix.service"; - description = '' + description = lib.mdDoc '' Name of the postfix systemd unit. ''; }; slice = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Name of the postfix systemd slice. - This overrides the <option>systemd.unit</option>. + This overrides the {option}`systemd.unit`. ''; }; journalPath = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Path to the systemd journal. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix b/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix index b479bcc33df..5e8dd21af85 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/postgres.nix @@ -11,7 +11,7 @@ in telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; @@ -19,14 +19,14 @@ in type = types.str; default = "user=postgres database=postgres host=/run/postgresql sslmode=disable"; example = "postgresql://username:password@localhost:5432/postgres?sslmode=disable"; - description = '' + description = lib.mdDoc '' Accepts PostgreSQL URI form and key=value form arguments. ''; }; runAsLocalSuperUser = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to run the exporter as the local 'postgres' super user. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/process.nix b/nixos/modules/services/monitoring/prometheus/exporters/process.nix index 666116991b5..278d6cd7807 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/process.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/process.nix @@ -18,11 +18,11 @@ in { name = "{{.Matches.Wrapped}} {{ .Matches.Args }}"; cmdline = [ "^/nix/store[^ ]*/(?P<Wrapped>[^ /]*) (?P<Args>.*)" ]; } ] ''; - description = '' + description = lib.mdDoc '' All settings expressed as an Nix attrset. Check the official documentation for the corresponding YAML - settings that can all be used here: <link xlink:href="https://github.com/ncabatoff/process-exporter"/> + settings that can all be used here: <https://github.com/ncabatoff/process-exporter> ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/pve.nix b/nixos/modules/services/monitoring/prometheus/exporters/pve.nix index ef708414c95..8e2573d084b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/pve.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/pve.nix @@ -20,7 +20,7 @@ in default = pkgs.prometheus-pve-exporter; defaultText = literalExpression "pkgs.prometheus-pve-exporter"; example = literalExpression "pkgs.prometheus-pve-exporter"; - description = '' + description = lib.mdDoc '' The package to use for prometheus-pve-exporter ''; }; @@ -29,7 +29,7 @@ in type = with types; nullOr path; default = null; example = "/etc/prometheus-pve-exporter/pve.env"; - description = '' + description = lib.mdDoc '' Path to the service's environment file. This path can either be a computed path in /nix/store or a path in the local filesystem. The environment file should NOT be stored in /nix/store as it contains passwords and/or keys in plain text. @@ -42,7 +42,7 @@ in type = with types; nullOr path; default = null; example = "/etc/prometheus-pve-exporter/pve.yml"; - description = '' + description = lib.mdDoc '' Path to the service's config file. This path can either be a computed path in /nix/store or a path in the local filesystem. The config file should NOT be stored in /nix/store as it will contain passwords and/or keys in plain text. @@ -57,42 +57,42 @@ in status = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Collect Node/VM/CT status ''; }; version = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Collect PVE version info ''; }; node = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Collect PVE node info ''; }; cluster = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Collect PVE cluster info ''; }; resources = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Collect PVE resources info ''; }; config = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Collect PVE onboot status ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/py-air-control.nix b/nixos/modules/services/monitoring/prometheus/exporters/py-air-control.nix index d9ab99221d9..f03b3c4df91 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/py-air-control.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/py-air-control.nix @@ -14,14 +14,14 @@ in deviceHostname = mkOption { type = types.str; example = "192.168.1.123"; - description = '' + description = lib.mdDoc '' The hostname of the air purification device from which to scrape the metrics. ''; }; protocol = mkOption { type = types.str; default = "http"; - description = '' + description = lib.mdDoc '' The protocol to use when communicating with the air purification device. Available: [http, coap, plain_coap] ''; @@ -29,8 +29,8 @@ in stateDir = mkOption { type = types.str; default = "prometheus-py-air-control-exporter"; - description = '' - Directory below <literal>/var/lib</literal> to store runtime data. + description = lib.mdDoc '' + Directory below `/var/lib` to store runtime data. This directory will be created automatically using systemd's StateDirectory mechanism. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/rspamd.nix b/nixos/modules/services/monitoring/prometheus/exporters/rspamd.nix index ed985751e42..0b48827f43f 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/rspamd.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/rspamd.nix @@ -69,7 +69,7 @@ in custom_label = "some_value"; } ''; - description = "Set of labels added to each metric."; + description = lib.mdDoc "Set of labels added to each metric."; }; }; serviceOpts.serviceConfig.ExecStart = '' diff --git a/nixos/modules/services/monitoring/prometheus/exporters/rtl_433.nix b/nixos/modules/services/monitoring/prometheus/exporters/rtl_433.nix index ef829a1b7d0..42bf1788aea 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/rtl_433.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/rtl_433.nix @@ -12,7 +12,7 @@ in options = { name = lib.mkOption { type = str; - description = "Name to match."; + description = lib.mdDoc "Name to match."; }; "${field}" = lib.mkOption { type = int; @@ -20,7 +20,7 @@ in }; location = lib.mkOption { type = str; - description = "Location to match."; + description = lib.mdDoc "Location to match."; }; }; }); @@ -30,9 +30,9 @@ in type = lib.types.str; default = "-C si"; example = "-C si -R 19"; - description = '' + description = lib.mdDoc '' Flags passed verbatim to rtl_433 binary. - Having <literal>-C si</literal> (the default) is recommended since only Celsius temperatures are parsed. + Having `-C si` (the default) is recommended since only Celsius temperatures are parsed. ''; }; channels = lib.mkOption { @@ -41,7 +41,7 @@ in example = [ { name = "Acurite"; channel = 6543; location = "Kitchen"; } ]; - description = '' + description = lib.mdDoc '' List of channel matchers to export. ''; }; @@ -51,7 +51,7 @@ in example = [ { name = "Nexus"; id = 1; location = "Bedroom"; } ]; - description = '' + description = lib.mdDoc '' List of ID matchers to export. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/script.nix b/nixos/modules/services/monitoring/prometheus/exporters/script.nix index 2a43fbcab3a..eab0e1d8a6b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/script.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/script.nix @@ -15,18 +15,18 @@ in name = mkOption { type = str; example = "sleep"; - description = "Name of the script."; + description = lib.mdDoc "Name of the script."; }; script = mkOption { type = str; example = "sleep 5"; - description = "Shell script to execute when metrics are requested."; + description = lib.mdDoc "Shell script to execute when metrics are requested."; }; timeout = mkOption { type = nullOr int; default = null; example = 60; - description = "Optional timeout for the script in seconds."; + description = lib.mdDoc "Optional timeout for the script in seconds."; }; }; }); @@ -37,11 +37,11 @@ in ]; } ''; - description = '' + description = lib.mdDoc '' All settings expressed as an Nix attrset. Check the official documentation for the corresponding YAML - settings that can all be used here: <link xlink:href="https://github.com/adhocteam/script_exporter#sample-configuration"/> + settings that can all be used here: <https://github.com/adhocteam/script_exporter#sample-configuration> ''; }; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/smartctl.nix b/nixos/modules/services/monitoring/prometheus/exporters/smartctl.nix index bac98364538..8906c25d503 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/smartctl.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/smartctl.nix @@ -24,7 +24,7 @@ in { example = literalExpression '' [ "/dev/sda", "/dev/nvme0n1" ]; ''; - description = '' + description = lib.mdDoc '' Paths to the disks that will be monitored. Will autodiscover all disks if none given. ''; @@ -33,7 +33,7 @@ in { type = types.str; default = "60s"; example = "2m"; - description = '' + description = lib.mdDoc '' Interval that limits how often a disk can be queried. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/smokeping.nix b/nixos/modules/services/monitoring/prometheus/exporters/smokeping.nix index 0181c341a7e..459f5842f54 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/smokeping.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/smokeping.nix @@ -17,27 +17,27 @@ in telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; pingInterval = mkOption { type = goDuration; default = "1s"; - description = '' + description = lib.mdDoc '' Interval between pings. ''; }; buckets = mkOption { type = types.commas; default = "5e-05,0.0001,0.0002,0.0004,0.0008,0.0016,0.0032,0.0064,0.0128,0.0256,0.0512,0.1024,0.2048,0.4096,0.8192,1.6384,3.2768,6.5536,13.1072,26.2144"; - description = '' + description = lib.mdDoc '' List of buckets to use for the response duration histogram. ''; }; hosts = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' List of endpoints to probe. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/snmp.nix b/nixos/modules/services/monitoring/prometheus/exporters/snmp.nix index de42663e67f..edc6e4b5022 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/snmp.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/snmp.nix @@ -11,7 +11,7 @@ in configurationPath = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Path to a snmp exporter configuration file. Mutually exclusive with 'configuration' option. ''; example = literalExpression "./snmp.yml"; @@ -20,7 +20,7 @@ in configuration = mkOption { type = types.nullOr types.attrs; default = null; - description = '' + description = lib.mdDoc '' Snmp exporter configuration as nix attribute set. Mutually exclusive with 'configurationPath' option. ''; example = { @@ -36,7 +36,7 @@ in logFormat = mkOption { type = types.enum ["logfmt" "json"]; default = "logfmt"; - description = '' + description = lib.mdDoc '' Output format of log messages. ''; }; @@ -44,7 +44,7 @@ in logLevel = mkOption { type = types.enum ["debug" "info" "warn" "error"]; default = "info"; - description = '' + description = lib.mdDoc '' Only log messages with the given severity or above. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/sql.nix b/nixos/modules/services/monitoring/prometheus/exporters/sql.nix index 3496fd9541f..678bc348679 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/sql.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/sql.nix @@ -7,7 +7,7 @@ let jobs = mkOption { type = attrsOf (submodule jobOptions); default = { }; - description = "An attrset of metrics scraping jobs to run."; + description = lib.mdDoc "An attrset of metrics scraping jobs to run."; }; }; }; @@ -15,23 +15,23 @@ let options = with types; { interval = mkOption { type = str; - description = '' + description = lib.mdDoc '' How often to run this job, specified in - <link xlink:href="https://golang.org/pkg/time/#ParseDuration">Go duration</link> format. + [Go duration](https://golang.org/pkg/time/#ParseDuration) format. ''; }; connections = mkOption { type = listOf str; - description = "A list of connection strings of the SQL servers to scrape metrics from"; + description = lib.mdDoc "A list of connection strings of the SQL servers to scrape metrics from"; }; startupSql = mkOption { type = listOf str; default = []; - description = "A list of SQL statements to execute once after making a connection."; + description = lib.mdDoc "A list of SQL statements to execute once after making a connection."; }; queries = mkOption { type = attrsOf (submodule queryOptions); - description = "SQL queries to run."; + description = lib.mdDoc "SQL queries to run."; }; }; }; @@ -40,20 +40,20 @@ let help = mkOption { type = nullOr str; default = null; - description = "A human-readable description of this metric."; + description = lib.mdDoc "A human-readable description of this metric."; }; labels = mkOption { type = listOf str; default = [ ]; - description = "A set of columns that will be used as Prometheus labels."; + description = lib.mdDoc "A set of columns that will be used as Prometheus labels."; }; query = mkOption { type = str; - description = "The SQL query to run."; + description = lib.mdDoc "The SQL query to run."; }; values = mkOption { type = listOf str; - description = "A set of columns that will be used as values of this metric."; + description = lib.mdDoc "A set of columns that will be used as values of this metric."; }; }; }; @@ -77,14 +77,14 @@ in configFile = mkOption { type = with types; nullOr path; default = null; - description = '' + description = lib.mdDoc '' Path to configuration file. ''; }; configuration = mkOption { type = with types; nullOr (submodule cfgOptions); default = null; - description = '' + description = lib.mdDoc '' Exporter configuration as nix attribute set. Mutually exclusive with 'configFile' option. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/surfboard.nix b/nixos/modules/services/monitoring/prometheus/exporters/surfboard.nix index 81c5c70ed93..b1d6760b40b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/surfboard.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/surfboard.nix @@ -11,7 +11,7 @@ in modemAddress = mkOption { type = types.str; default = "192.168.100.1"; - description = '' + description = lib.mdDoc '' The hostname or IP of the cable modem. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/tor.nix b/nixos/modules/services/monitoring/prometheus/exporters/tor.nix index 36c473677ef..edf9b57607a 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/tor.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/tor.nix @@ -11,7 +11,7 @@ in torControlAddress = mkOption { type = types.str; default = "127.0.0.1"; - description = '' + description = lib.mdDoc '' Tor control IP address or hostname. ''; }; @@ -19,7 +19,7 @@ in torControlPort = mkOption { type = types.int; default = 9051; - description = '' + description = lib.mdDoc '' Tor control port. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/unbound.nix b/nixos/modules/services/monitoring/prometheus/exporters/unbound.nix index cf0efddd340..f52d92a73d5 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/unbound.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/unbound.nix @@ -12,7 +12,7 @@ in # TODO: add shm when upstream implemented it type = types.enum [ "tcp" "uds" ]; default = "uds"; - description = '' + description = lib.mdDoc '' Which methods the exporter uses to get the information from unbound. ''; }; @@ -20,7 +20,7 @@ in telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; @@ -29,7 +29,7 @@ in type = types.nullOr types.str; default = null; example = "/run/unbound/unbound.socket"; - description = '' + description = lib.mdDoc '' Path to the unbound socket for uds mode or the control interface port for tcp mode. Example: diff --git a/nixos/modules/services/monitoring/prometheus/exporters/unifi.nix b/nixos/modules/services/monitoring/prometheus/exporters/unifi.nix index 8d0e8764001..70f26d9783b 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/unifi.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/unifi.nix @@ -11,7 +11,7 @@ in unifiAddress = mkOption { type = types.str; example = "https://10.0.0.1:8443"; - description = '' + description = lib.mdDoc '' URL of the UniFi Controller API. ''; }; @@ -19,7 +19,7 @@ in unifiInsecure = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If enabled skip the verification of the TLS certificate of the UniFi Controller API. Use with caution. ''; @@ -28,14 +28,14 @@ in unifiUsername = mkOption { type = types.str; example = "ReadOnlyUser"; - description = '' + description = lib.mdDoc '' username for authentication against UniFi Controller API. ''; }; unifiPassword = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Password for authentication against UniFi Controller API. ''; }; @@ -44,7 +44,7 @@ in type = types.str; default = "5s"; example = "2m"; - description = '' + description = lib.mdDoc '' Timeout including unit for UniFi Controller API requests. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/varnish.nix b/nixos/modules/services/monitoring/prometheus/exporters/varnish.nix index ede6028933a..a7e5b41dffc 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/varnish.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/varnish.nix @@ -11,35 +11,35 @@ in noExit = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Do not exit server on Varnish scrape errors. ''; }; withGoMetrics = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Export go runtime and http handler metrics. ''; }; verbose = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable verbose logging. ''; }; raw = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable raw stdout logging without timestamps. ''; }; varnishStatPath = mkOption { type = types.str; default = "varnishstat"; - description = '' + description = lib.mdDoc '' Path to varnishstat. ''; }; @@ -47,21 +47,21 @@ in type = types.nullOr types.str; default = config.services.varnish.stateDir; defaultText = lib.literalExpression "config.services.varnish.stateDir"; - description = '' + description = lib.mdDoc '' varnishstat -n value. ''; }; healthPath = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Path under which to expose healthcheck. Disabled unless configured. ''; }; telemetryPath = mkOption { type = types.str; default = "/metrics"; - description = '' + description = lib.mdDoc '' Path under which to expose metrics. ''; }; diff --git a/nixos/modules/services/monitoring/prometheus/exporters/wireguard.nix b/nixos/modules/services/monitoring/prometheus/exporters/wireguard.nix index 2d329a1af1c..20631f2af93 100644 --- a/nixos/modules/services/monitoring/prometheus/exporters/wireguard.nix +++ b/nixos/modules/services/monitoring/prometheus/exporters/wireguard.nix @@ -17,13 +17,13 @@ in { type = with types; nullOr (either path str); default = null; - description = '' + description = lib.mdDoc '' Path to the Wireguard Config to - <link xlink:href="https://github.com/MindFlavor/prometheus_wireguard_exporter/tree/2.0.0#usage">add the peer's name to the stats of a peer</link>. + [add the peer's name to the stats of a peer](https://github.com/MindFlavor/prometheus_wireguard_exporter/tree/2.0.0#usage). - Please note that <literal>networking.wg-quick</literal> is required for this feature - as <literal>networking.wireguard</literal> uses - <citerefentry><refentrytitle>wg</refentrytitle><manvolnum>8</manvolnum></citerefentry> + Please note that `networking.wg-quick` is required for this feature + as `networking.wireguard` uses + {manpage}`wg(8)` to set the peers up. ''; }; @@ -31,18 +31,18 @@ in { singleSubnetPerField = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' By default, all allowed IPs and subnets are comma-separated in the - <literal>allowed_ips</literal> field. With this option enabled, - a single IP and subnet will be listed in fields like <literal>allowed_ip_0</literal>, - <literal>allowed_ip_1</literal> and so on. + `allowed_ips` field. With this option enabled, + a single IP and subnet will be listed in fields like `allowed_ip_0`, + `allowed_ip_1` and so on. ''; }; withRemoteIp = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether or not the remote IP of a WireGuard peer should be exposed via prometheus. ''; }; diff --git a/nixos/modules/services/network-filesystems/netatalk.nix b/nixos/modules/services/network-filesystems/netatalk.nix index fd976424734..838a374ba6c 100644 --- a/nixos/modules/services/network-filesystems/netatalk.nix +++ b/nixos/modules/services/network-filesystems/netatalk.nix @@ -32,18 +32,18 @@ in { "read only" = true; }; }; - description = '' + description = lib.mdDoc '' Configuration for Netatalk. See - <citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`afp.conf(5)`. ''; }; extmap = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' File name extension mappings. - See <citerefentry><refentrytitle>extmap.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. for more information. + See {manpage}`extmap.conf(5)`. for more information. ''; }; diff --git a/nixos/modules/services/network-filesystems/nfsd.nix b/nixos/modules/services/network-filesystems/nfsd.nix index 39f43d3dac7..c9e1cbcbbda 100644 --- a/nixos/modules/services/network-filesystems/nfsd.nix +++ b/nixos/modules/services/network-filesystems/nfsd.nix @@ -42,19 +42,19 @@ in exports = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Contents of the /etc/exports file. See - <citerefentry><refentrytitle>exports</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the format. + {manpage}`exports(5)` for the format. ''; }; hostName = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Hostname or address on which NFS requests will be accepted. - Default is all. See the <option>-H</option> option in - <citerefentry><refentrytitle>nfsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + Default is all. See the {option}`-H` option in + {manpage}`nfsd(8)`. ''; }; diff --git a/nixos/modules/services/network-filesystems/openafs/client.nix b/nixos/modules/services/network-filesystems/openafs/client.nix index c8cc5052c2a..bb0fee087e6 100644 --- a/nixos/modules/services/network-filesystems/openafs/client.nix +++ b/nixos/modules/services/network-filesystems/openafs/client.nix @@ -33,29 +33,29 @@ in enable = mkOption { default = false; type = types.bool; - description = "Whether to enable the OpenAFS client."; + description = lib.mdDoc "Whether to enable the OpenAFS client."; }; afsdb = mkOption { default = true; type = types.bool; - description = "Resolve cells via AFSDB DNS records."; + description = lib.mdDoc "Resolve cells via AFSDB DNS records."; }; cellName = mkOption { default = ""; type = types.str; - description = "Cell name."; + description = lib.mdDoc "Cell name."; example = "grand.central.org"; }; cellServDB = mkOption { default = []; type = with types; listOf (submodule { options = cellServDBConfig; }); - description = '' + description = lib.mdDoc '' This cell's database server records, added to the global CellServDB. See CellServDB(5) man page for syntax. Ignored when - <literal>afsdb</literal> is set to <literal>true</literal>. + `afsdb` is set to `true`. ''; example = [ { ip = "1.2.3.4"; dnsname = "first.afsdb.server.dns.fqdn.org"; } @@ -67,15 +67,15 @@ in blocks = mkOption { default = 100000; type = types.int; - description = "Cache size in 1KB blocks."; + description = lib.mdDoc "Cache size in 1KB blocks."; }; chunksize = mkOption { default = 0; type = types.ints.between 0 30; - description = '' + description = lib.mdDoc '' Size of each cache chunk given in powers of - 2. <literal>0</literal> resets the chunk size to its default + 2. `0` resets the chunk size to its default values (13 (8 KB) for memcache, 18-20 (256 KB to 1 MB) for diskcache). Maximum value is 30. Important performance parameter. Set to higher values when dealing with large files. @@ -85,13 +85,13 @@ in directory = mkOption { default = "/var/cache/openafs"; type = types.str; - description = "Cache directory."; + description = lib.mdDoc "Cache directory."; }; diskless = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Use in-memory cache for diskless machines. Has no real performance benefit anymore. ''; @@ -101,13 +101,13 @@ in crypt = mkOption { default = true; type = types.bool; - description = "Whether to enable (weak) protocol encryption."; + description = lib.mdDoc "Whether to enable (weak) protocol encryption."; }; daemons = mkOption { default = 2; type = types.int; - description = '' + description = lib.mdDoc '' Number of daemons to serve user requests. Numbers higher than 6 usually do no increase performance. Default is sufficient for up to five concurrent users. @@ -117,9 +117,9 @@ in fakestat = mkOption { default = false; type = types.bool; - description = '' - Return fake data on stat() calls. If <literal>true</literal>, - always do so. If <literal>false</literal>, only do so for + description = lib.mdDoc '' + Return fake data on stat() calls. If `true`, + always do so. If `false`, only do so for cross-cell mounts (as these are potentially expensive). ''; }; @@ -127,9 +127,9 @@ in inumcalc = mkOption { default = "compat"; type = types.strMatching "compat|md5"; - description = '' - Inode calculation method. <literal>compat</literal> is - computationally less expensive, but <literal>md5</literal> greatly + description = lib.mdDoc '' + Inode calculation method. `compat` is + computationally less expensive, but `md5` greatly reduces the likelihood of inode collisions in larger scenarios involving multiple cells mounted into one AFS space. ''; @@ -138,9 +138,9 @@ in mountPoint = mkOption { default = "/afs"; type = types.str; - description = '' + description = lib.mdDoc '' Mountpoint of the AFS file tree, conventionally - <literal>/afs</literal>. When set to a different value, only + `/afs`. When set to a different value, only cross-cells that use the same value can be accessed. ''; }; @@ -150,28 +150,28 @@ in default = config.boot.kernelPackages.openafs; defaultText = literalExpression "config.boot.kernelPackages.openafs"; type = types.package; - description = "OpenAFS kernel module package. MUST match the userland package!"; + description = lib.mdDoc "OpenAFS kernel module package. MUST match the userland package!"; }; programs = mkOption { default = getBin pkgs.openafs; defaultText = literalExpression "getBin pkgs.openafs"; type = types.package; - description = "OpenAFS programs package. MUST match the kernel module package!"; + description = lib.mdDoc "OpenAFS programs package. MUST match the kernel module package!"; }; }; sparse = mkOption { default = true; type = types.bool; - description = "Minimal cell list in /afs."; + description = lib.mdDoc "Minimal cell list in /afs."; }; startDisconnected = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Start up in disconnected mode. You need to execute - <literal>fs disco online</literal> (as root) to switch to + `fs disco online` (as root) to switch to connected mode. Useful for roaming devices. ''; }; diff --git a/nixos/modules/services/network-filesystems/openafs/lib.nix b/nixos/modules/services/network-filesystems/openafs/lib.nix index e068ee761c2..80628f4dfaf 100644 --- a/nixos/modules/services/network-filesystems/openafs/lib.nix +++ b/nixos/modules/services/network-filesystems/openafs/lib.nix @@ -17,13 +17,13 @@ in { type = types.str; default = ""; example = "1.2.3.4"; - description = "IP Address of a database server"; + description = lib.mdDoc "IP Address of a database server"; }; dnsname = mkOption { type = types.str; default = ""; example = "afs.example.org"; - description = "DNS full-qualified domain name of a database server"; + description = lib.mdDoc "DNS full-qualified domain name of a database server"; }; }; diff --git a/nixos/modules/services/network-filesystems/openafs/server.nix b/nixos/modules/services/network-filesystems/openafs/server.nix index 9c974335def..1c615d3bfb6 100644 --- a/nixos/modules/services/network-filesystems/openafs/server.nix +++ b/nixos/modules/services/network-filesystems/openafs/server.nix @@ -49,13 +49,13 @@ in { enable = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable the OpenAFS server. An OpenAFS server needs a complex setup. So, be aware that enabling this service and setting some options does not give you a turn-key-ready solution. You need at least a running Kerberos 5 setup, as OpenAFS relies on it for authentication. See the Guide "QuickStartUnix" coming with - <literal>pkgs.openafs.doc</literal> for complete setup + `pkgs.openafs.doc` for complete setup instructions. ''; }; @@ -63,27 +63,27 @@ in { advertisedAddresses = mkOption { type = types.listOf types.str; default = []; - description = "List of IP addresses this server is advertised under. See NetInfo(5)"; + description = lib.mdDoc "List of IP addresses this server is advertised under. See NetInfo(5)"; }; cellName = mkOption { default = ""; type = types.str; - description = "Cell name, this server will serve."; + description = lib.mdDoc "Cell name, this server will serve."; example = "grand.central.org"; }; cellServDB = mkOption { default = []; type = with types; listOf (submodule [ { options = cellServDBConfig;} ]); - description = "Definition of all cell-local database server machines."; + description = lib.mdDoc "Definition of all cell-local database server machines."; }; package = mkOption { default = pkgs.openafs.server or pkgs.openafs; defaultText = literalExpression "pkgs.openafs.server or pkgs.openafs"; type = types.package; - description = "OpenAFS package for the server binaries"; + description = lib.mdDoc "OpenAFS package for the server binaries"; }; roles = { @@ -91,33 +91,33 @@ in { enable = mkOption { default = true; type = types.bool; - description = "Fileserver role, serves files and volumes from its local storage."; + description = lib.mdDoc "Fileserver role, serves files and volumes from its local storage."; }; fileserverArgs = mkOption { default = "-vattachpar 128 -vhashsize 11 -L -rxpck 400 -cb 1000000"; type = types.str; - description = "Arguments to the dafileserver process. See its man page."; + description = lib.mdDoc "Arguments to the dafileserver process. See its man page."; }; volserverArgs = mkOption { default = ""; type = types.str; - description = "Arguments to the davolserver process. See its man page."; + description = lib.mdDoc "Arguments to the davolserver process. See its man page."; example = "-sync never"; }; salvageserverArgs = mkOption { default = ""; type = types.str; - description = "Arguments to the salvageserver process. See its man page."; + description = lib.mdDoc "Arguments to the salvageserver process. See its man page."; example = "-showlog"; }; salvagerArgs = mkOption { default = ""; type = types.str; - description = "Arguments to the dasalvager process. See its man page."; + description = lib.mdDoc "Arguments to the dasalvager process. See its man page."; example = "-showlog -showmounts"; }; }; @@ -126,10 +126,10 @@ in { enable = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Database server role, maintains the Volume Location Database, Protection Database (and Backup Database, see - <literal>backup</literal> role). There can be multiple + `backup` role). There can be multiple servers in the database role for replication, which then need reliable network connection to each other. @@ -141,14 +141,14 @@ in { vlserverArgs = mkOption { default = ""; type = types.str; - description = "Arguments to the vlserver process. See its man page."; + description = lib.mdDoc "Arguments to the vlserver process. See its man page."; example = "-rxbind"; }; ptserverArgs = mkOption { default = ""; type = types.str; - description = "Arguments to the ptserver process. See its man page."; + description = lib.mdDoc "Arguments to the ptserver process. See its man page."; example = "-restricted -default_access S---- S-M---"; }; }; @@ -157,9 +157,9 @@ in { enable = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Backup server role. Use in conjunction with the - <literal>database</literal> role to maintain the Backup + `database` role to maintain the Backup Database. Normally only used in conjunction with tape storage or IBM's Tivoli Storage Manager. ''; @@ -168,14 +168,14 @@ in { buserverArgs = mkOption { default = ""; type = types.str; - description = "Arguments to the buserver process. See its man page."; + description = lib.mdDoc "Arguments to the buserver process. See its man page."; example = "-p 8"; }; cellServDB = mkOption { default = []; type = with types; listOf (submodule [ { options = cellServDBConfig;} ]); - description = '' + description = lib.mdDoc '' Definition of all cell-local backup database server machines. Use this when your cell uses less backup database servers than other database server machines. @@ -187,7 +187,7 @@ in { dottedPrincipals= mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' If enabled, allow principal names containing (.) dots. Enabling this has security implications! ''; @@ -196,11 +196,11 @@ in { udpPacketSize = mkOption { default = 1310720; type = types.int; - description = '' + description = lib.mdDoc '' UDP packet size to use in Bytes. Higher values can speed up communications. The default of 1 MB is a sufficient in most cases. Make sure to increase the kernel's UDP buffer size - accordingly via <literal>net.core(w|r|opt)mem_max</literal> + accordingly via `net.core(w|r|opt)mem_max` sysctl. ''; }; diff --git a/nixos/modules/services/network-filesystems/rsyncd.nix b/nixos/modules/services/network-filesystems/rsyncd.nix index 059de2089ed..d65113c84b3 100644 --- a/nixos/modules/services/network-filesystems/rsyncd.nix +++ b/nixos/modules/services/network-filesystems/rsyncd.nix @@ -39,9 +39,9 @@ in { "secrets file" = "/etc/rsyncd.secrets"; }; }; - description = '' + description = lib.mdDoc '' Configuration for rsyncd. See - <citerefentry><refentrytitle>rsyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`rsyncd.conf(5)`. ''; }; diff --git a/nixos/modules/services/network-filesystems/webdav.nix b/nixos/modules/services/network-filesystems/webdav.nix index 8c39876a393..b7c07b8c12c 100644 --- a/nixos/modules/services/network-filesystems/webdav.nix +++ b/nixos/modules/services/network-filesystems/webdav.nix @@ -67,8 +67,8 @@ in environmentFile = mkOption { type = types.nullOr types.path; default = null; - description = '' - Environment file as defined in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + description = lib.mdDoc '' + Environment file as defined in {manpage}`systemd.exec(5)`. ''; }; }; diff --git a/nixos/modules/services/networking/avahi-daemon.nix b/nixos/modules/services/networking/avahi-daemon.nix index 0be77fa3d0d..56113bd3459 100644 --- a/nixos/modules/services/networking/avahi-daemon.nix +++ b/nixos/modules/services/networking/avahi-daemon.nix @@ -150,9 +150,9 @@ in '''; } ''; - description = '' + description = lib.mdDoc '' Specify custom service definitions which are placed in the avahi service directory. - See the <citerefentry><refentrytitle>avahi.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> manpage for detailed information. + See the {manpage}`avahi.service(5)` manpage for detailed information. ''; }; diff --git a/nixos/modules/services/networking/keepalived/default.nix b/nixos/modules/services/networking/keepalived/default.nix index c9ac2ee2599..768c8e4b13c 100644 --- a/nixos/modules/services/networking/keepalived/default.nix +++ b/nixos/modules/services/networking/keepalived/default.nix @@ -147,7 +147,7 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable Keepalived. ''; }; @@ -155,7 +155,7 @@ in enableScriptSecurity = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Don't run scripts configured to be run as root if any part of the path is writable by a non-root user. ''; }; @@ -165,7 +165,7 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable the builtin AgentX subagent. ''; }; @@ -173,7 +173,7 @@ in socket = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Socket to use for connecting to SNMP master agent. If this value is set to null, keepalived's default will be used, which is unix:/var/agentx/master, unless using a network namespace, when the @@ -184,7 +184,7 @@ in enableKeepalived = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SNMP handling of vrrp element of KEEPALIVED MIB. ''; }; @@ -192,7 +192,7 @@ in enableChecker = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SNMP handling of checker element of KEEPALIVED MIB. ''; }; @@ -200,7 +200,7 @@ in enableRfc = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SNMP handling of RFC2787 and RFC6527 VRRP MIBs. ''; }; @@ -208,7 +208,7 @@ in enableRfcV2 = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SNMP handling of RFC2787 VRRP MIB. ''; }; @@ -216,7 +216,7 @@ in enableRfcV3 = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SNMP handling of RFC6527 VRRP MIB. ''; }; @@ -224,7 +224,7 @@ in enableTraps = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SNMP traps. ''; }; @@ -236,7 +236,7 @@ in inherit lib; })); default = {}; - description = "Declarative vrrp script config"; + description = lib.mdDoc "Declarative vrrp script config"; }; vrrpInstances = mkOption { @@ -244,13 +244,13 @@ in inherit lib; })); default = {}; - description = "Declarative vhost config"; + description = lib.mdDoc "Declarative vhost config"; }; extraGlobalDefs = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra lines to be added verbatim to the 'global_defs' block of the configuration file ''; @@ -259,7 +259,7 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra lines to be added verbatim to the configuration file. ''; }; diff --git a/nixos/modules/services/networking/keepalived/virtual-ip-options.nix b/nixos/modules/services/networking/keepalived/virtual-ip-options.nix index 1b8889b1b47..1fa6a0ee3bf 100644 --- a/nixos/modules/services/networking/keepalived/virtual-ip-options.nix +++ b/nixos/modules/services/networking/keepalived/virtual-ip-options.nix @@ -6,7 +6,7 @@ with lib; addr = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' IP address, optionally with a netmask: IPADDR[/MASK] ''; }; @@ -14,7 +14,7 @@ with lib; brd = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The broadcast address on the interface. ''; }; @@ -22,7 +22,7 @@ with lib; dev = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The name of the device to add the address to. ''; }; @@ -30,7 +30,7 @@ with lib; scope = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The scope of the area where this address is valid. ''; }; @@ -38,7 +38,7 @@ with lib; label = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Each address may be tagged with a label string. In order to preserve compatibility with Linux-2.0 net aliases, this string must coincide with the name of the device or must be prefixed with the device name followed diff --git a/nixos/modules/services/networking/keepalived/vrrp-instance-options.nix b/nixos/modules/services/networking/keepalived/vrrp-instance-options.nix index e96dde5fa89..20e5558d782 100644 --- a/nixos/modules/services/networking/keepalived/vrrp-instance-options.nix +++ b/nixos/modules/services/networking/keepalived/vrrp-instance-options.nix @@ -6,7 +6,7 @@ with lib; interface = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Interface for inside_network, bound by vrrp. ''; }; @@ -14,7 +14,7 @@ with lib; state = mkOption { type = types.enum [ "MASTER" "BACKUP" ]; default = "BACKUP"; - description = '' + description = lib.mdDoc '' Initial state. As soon as the other machine(s) come up, an election will be held and the machine with the highest "priority" will become MASTER. So the entry here doesn't matter a whole lot. @@ -23,7 +23,7 @@ with lib; virtualRouterId = mkOption { type = types.int; - description = '' + description = lib.mdDoc '' Arbitrary unique number 0..255. Used to differentiate multiple instances of vrrpd running on the same NIC (and hence same socket). ''; @@ -32,7 +32,7 @@ with lib; priority = mkOption { type = types.int; default = 100; - description = '' + description = lib.mdDoc '' For electing MASTER, highest priority wins. To be MASTER, make 50 more than other machines. ''; @@ -41,7 +41,7 @@ with lib; noPreempt = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' VRRP will normally preempt a lower priority machine when a higher priority machine comes online. "nopreempt" allows the lower priority machine to maintain the master role, even when a higher priority machine @@ -53,7 +53,7 @@ with lib; useVmac = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Use VRRP Virtual MAC. ''; }; @@ -61,7 +61,7 @@ with lib; vmacInterface = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Name of the vmac interface to use. keepalived will come up with a name if you don't specify one. ''; @@ -70,7 +70,7 @@ with lib; vmacXmitBase = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Send/Recv VRRP messages from base interface instead of VMAC interface. ''; }; @@ -78,7 +78,7 @@ with lib; unicastSrcIp = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Default IP for binding vrrpd is the primary IP on interface. If you want to hide location of vrrpd, use this IP as src_addr for unicast vrrp packets. @@ -88,7 +88,7 @@ with lib; unicastPeers = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Do not send VRRP adverts over VRRP multicast group. Instead it sends adverts to the following list of ip addresses using unicast design fashion. It can be cool to use VRRP FSM and features in a networking @@ -103,27 +103,27 @@ with lib; })); default = []; # TODO: example - description = "Declarative vhost config"; + description = lib.mdDoc "Declarative vhost config"; }; trackScripts = mkOption { type = types.listOf types.str; default = []; example = [ "chk_cmd1" "chk_cmd2" ]; - description = "List of script names to invoke for health tracking."; + description = lib.mdDoc "List of script names to invoke for health tracking."; }; trackInterfaces = mkOption { type = types.listOf types.str; default = []; example = [ "eth0" "eth1" ]; - description = "List of network interfaces to monitor for health tracking."; + description = lib.mdDoc "List of network interfaces to monitor for health tracking."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra lines to be added verbatim to the vrrp_instance section. ''; }; diff --git a/nixos/modules/services/networking/keepalived/vrrp-script-options.nix b/nixos/modules/services/networking/keepalived/vrrp-script-options.nix index df7a89cff8c..852d6b0ec26 100644 --- a/nixos/modules/services/networking/keepalived/vrrp-script-options.nix +++ b/nixos/modules/services/networking/keepalived/vrrp-script-options.nix @@ -8,55 +8,55 @@ with lib.types; script = mkOption { type = str; example = literalExpression ''"''${pkgs.curl} -f http://localhost:80"''; - description = "(Path of) Script command to execute followed by args, i.e. cmd [args]..."; + description = lib.mdDoc "(Path of) Script command to execute followed by args, i.e. cmd [args]..."; }; interval = mkOption { type = int; default = 1; - description = "Seconds between script invocations."; + description = lib.mdDoc "Seconds between script invocations."; }; timeout = mkOption { type = int; default = 5; - description = "Seconds after which script is considered to have failed."; + description = lib.mdDoc "Seconds after which script is considered to have failed."; }; weight = mkOption { type = int; default = 0; - description = "Following a failure, adjust the priority by this weight."; + description = lib.mdDoc "Following a failure, adjust the priority by this weight."; }; rise = mkOption { type = int; default = 5; - description = "Required number of successes for OK transition."; + description = lib.mdDoc "Required number of successes for OK transition."; }; fall = mkOption { type = int; default = 3; - description = "Required number of failures for KO transition."; + description = lib.mdDoc "Required number of failures for KO transition."; }; user = mkOption { type = str; default = "keepalived_script"; - description = "Name of user to run the script under."; + description = lib.mdDoc "Name of user to run the script under."; }; group = mkOption { type = nullOr str; default = null; - description = "Name of group to run the script under. Defaults to user group."; + description = lib.mdDoc "Name of group to run the script under. Defaults to user group."; }; extraConfig = mkOption { type = lines; default = ""; - description = "Extra lines to be added verbatim to the vrrp_script section."; + description = lib.mdDoc "Extra lines to be added verbatim to the vrrp_script section."; }; }; diff --git a/nixos/modules/services/networking/nbd.nix b/nixos/modules/services/networking/nbd.nix index bd52c624426..76ca11dfea7 100644 --- a/nixos/modules/services/networking/nbd.nix +++ b/nixos/modules/services/networking/nbd.nix @@ -56,9 +56,9 @@ in default = { allowlist = false; }; - description = '' + description = lib.mdDoc '' Extra options for the server. See - <citerefentry><refentrytitle>nbd-server</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`nbd-server(5)`. ''; }; @@ -87,9 +87,9 @@ in flush = true; fua = true; }; - description = '' + description = lib.mdDoc '' Extra options for this export. See - <citerefentry><refentrytitle>nbd-server</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`nbd-server(5)`. ''; }; }; diff --git a/nixos/modules/services/networking/networkmanager.nix b/nixos/modules/services/networking/networkmanager.nix index f2ca3cf30f1..d5d562e7ba5 100644 --- a/nixos/modules/services/networking/networkmanager.nix +++ b/nixos/modules/services/networking/networkmanager.nix @@ -173,14 +173,14 @@ in { str ])); default = {}; - description = '' + description = lib.mdDoc '' Configuration for the [connection] section of NetworkManager.conf. Refer to - <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html"> + [ https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#id-1.2.3.11 - </link> + ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html) or - <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`NetworkManager.conf(5)` for more information. ''; }; @@ -188,14 +188,14 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration appended to the generated NetworkManager.conf. Refer to - <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html"> + [ https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html - </link> + ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html) or - <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`NetworkManager.conf(5)` for more information. ''; }; @@ -203,15 +203,15 @@ in { unmanaged = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' List of interfaces that will not be managed by NetworkManager. Interface name can be specified here, but if you need more fidelity, refer to - <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#device-spec"> + [ https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#device-spec - </link> + ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html#device-spec) or the "Device List Format" Appendix of - <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`NetworkManager.conf(5)`. ''; }; @@ -318,15 +318,15 @@ in { dns = mkOption { type = types.enum [ "default" "dnsmasq" "unbound" "systemd-resolved" "none" ]; default = "default"; - description = '' - Set the DNS (<literal>resolv.conf</literal>) processing mode. + description = lib.mdDoc '' + Set the DNS (`resolv.conf`) processing mode. A description of these modes can be found in the main section of - <link xlink:href="https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html"> + [ https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html - </link> + ](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html) or in - <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`NetworkManager.conf(5)`. ''; }; diff --git a/nixos/modules/services/networking/nghttpx/backend-submodule.nix b/nixos/modules/services/networking/nghttpx/backend-submodule.nix index eb559e926e7..af99b21c9ab 100644 --- a/nixos/modules/services/networking/nghttpx/backend-submodule.nix +++ b/nixos/modules/services/networking/nghttpx/backend-submodule.nix @@ -13,7 +13,7 @@ host = "127.0.0.1"; port = 80; }; - description = '' + description = lib.mdDoc '' Backend server location specified as either a host:port pair or a unix domain docket. ''; @@ -27,7 +27,7 @@ "/somepath" ]; default = []; - description = '' + description = lib.mdDoc '' List of nghttpx backend patterns. Please see https://nghttp2.org/documentation/nghttpx.1.html#cmdoption-nghttpx-b @@ -42,7 +42,7 @@ tls = true; }; default = null; - description = '' + description = lib.mdDoc '' Parameters to configure a backend. ''; }; diff --git a/nixos/modules/services/networking/nghttpx/frontend-submodule.nix b/nixos/modules/services/networking/nghttpx/frontend-submodule.nix index 887ef450213..3175df20eec 100644 --- a/nixos/modules/services/networking/nghttpx/frontend-submodule.nix +++ b/nixos/modules/services/networking/nghttpx/frontend-submodule.nix @@ -13,7 +13,7 @@ host = "127.0.0.1"; port = 80; }; - description = '' + description = lib.mdDoc '' Frontend server interface binding specification as either a host:port pair or a unix domain docket. @@ -28,7 +28,7 @@ tls = "tls"; }; default = null; - description = '' + description = lib.mdDoc '' Parameters to configure a backend. ''; }; diff --git a/nixos/modules/services/networking/nghttpx/nghttpx-options.nix b/nixos/modules/services/networking/nghttpx/nghttpx-options.nix index 51f1d081b97..13c328b4180 100644 --- a/nixos/modules/services/networking/nghttpx/nghttpx-options.nix +++ b/nixos/modules/services/networking/nghttpx/nghttpx-options.nix @@ -4,7 +4,7 @@ frontends = lib.mkOption { type = lib.types.listOf (lib.types.submodule (import ./frontend-submodule.nix)); - description = '' + description = lib.mdDoc '' A list of frontend listener specifications. ''; example = [ @@ -22,7 +22,7 @@ backends = lib.mkOption { type = lib.types.listOf (lib.types.submodule (import ./backend-submodule.nix)); - description = '' + description = lib.mdDoc '' A list of backend specifications. ''; example = [ @@ -42,10 +42,10 @@ tls = lib.mkOption { type = lib.types.nullOr (lib.types.submodule (import ./tls-submodule.nix)); default = null; - description = '' + description = lib.mdDoc '' TLS certificate and key paths. Note that this does not enable TLS for a frontend listener, to do so, a frontend - specification must set <literal>params.tls</literal> to true. + specification must set `params.tls` to true. ''; example = { key = "/etc/ssl/keys/server.key"; @@ -56,7 +56,7 @@ extraConfig = lib.mkOption { type = lib.types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration options to be appended to the generated configuration file. ''; @@ -65,7 +65,7 @@ single-process = lib.mkOption { type = lib.types.bool; default = false; - description = '' + description = lib.mdDoc '' Run this program in a single process mode for debugging purpose. Without this option, nghttpx creates at least 2 processes: master and worker processes. If this option is @@ -81,7 +81,7 @@ backlog = lib.mkOption { type = lib.types.int; default = 65536; - description = '' + description = lib.mdDoc '' Listen backlog size. Please see https://nghttp2.org/documentation/nghttpx.1.html#cmdoption-nghttpx--backlog @@ -95,7 +95,7 @@ "IPv6" ]; default = "auto"; - description = '' + description = lib.mdDoc '' Specify address family of backend connections. If "auto" is given, both IPv4 and IPv6 are considered. If "IPv4" is given, only IPv4 address is considered. If "IPv6" is given, only IPv6 @@ -108,7 +108,7 @@ workers = lib.mkOption { type = lib.types.int; default = 1; - description = '' + description = lib.mdDoc '' Set the number of worker threads. Please see https://nghttp2.org/documentation/nghttpx.1.html#cmdoption-nghttpx-n @@ -118,7 +118,7 @@ single-thread = lib.mkOption { type = lib.types.bool; default = false; - description = '' + description = lib.mdDoc '' Run everything in one thread inside the worker process. This feature is provided for better debugging experience, or for the platforms which lack thread support. If threading is diff --git a/nixos/modules/services/networking/soju.nix b/nixos/modules/services/networking/soju.nix index 887a4c137d8..dddacea2004 100644 --- a/nixos/modules/services/networking/soju.nix +++ b/nixos/modules/services/networking/soju.nix @@ -32,10 +32,10 @@ in listen = mkOption { type = types.listOf types.str; default = [ ":6697" ]; - description = '' + description = lib.mdDoc '' Where soju should listen for incoming connections. See the - <literal>listen</literal> directive in - <citerefentry><refentrytitle>soju</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + `listen` directive in + {manpage}`soju(1)`. ''; }; @@ -69,10 +69,10 @@ in httpOrigins = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' List of allowed HTTP origins for WebSocket listeners. The parameters are interpreted as shell patterns, see - <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`glob(7)`. ''; }; diff --git a/nixos/modules/services/networking/ssh/sshd.nix b/nixos/modules/services/networking/ssh/sshd.nix index 6beafb8c7c8..beb411f204b 100644 --- a/nixos/modules/services/networking/ssh/sshd.nix +++ b/nixos/modules/services/networking/ssh/sshd.nix @@ -156,10 +156,10 @@ in gatewayPorts = mkOption { type = types.str; default = "no"; - description = '' + description = lib.mdDoc '' Specifies whether remote hosts are allowed to connect to ports forwarded for the client. See - <citerefentry><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`sshd_config(5)`. ''; }; @@ -236,10 +236,10 @@ in [ { type = "rsa"; bits = 4096; path = "/etc/ssh/ssh_host_rsa_key"; rounds = 100; openSSHFormat = true; } { type = "ed25519"; path = "/etc/ssh/ssh_host_ed25519_key"; rounds = 100; comment = "key comment"; } ]; - description = '' + description = lib.mdDoc '' NixOS can automatically generate SSH host keys. This option specifies the path, type and size of each key. See - <citerefentry><refentrytitle>ssh-keygen</refentrytitle><manvolnum>1</manvolnum></citerefentry> for supported types + {manpage}`ssh-keygen(1)` for supported types and sizes. ''; }; diff --git a/nixos/modules/services/networking/strongswan-swanctl/module.nix b/nixos/modules/services/networking/strongswan-swanctl/module.nix index 9287943fcde..a92834f0ecf 100644 --- a/nixos/modules/services/networking/strongswan-swanctl/module.nix +++ b/nixos/modules/services/networking/strongswan-swanctl/module.nix @@ -14,7 +14,7 @@ in { type = types.package; default = pkgs.strongswan; defaultText = literalExpression "pkgs.strongswan"; - description = '' + description = lib.mdDoc '' The strongswan derivation to use. ''; }; @@ -22,8 +22,8 @@ in { strongswan.extraConfig = mkOption { type = types.str; default = ""; - description = '' - Contents of the <literal>strongswan.conf</literal> file. + description = lib.mdDoc '' + Contents of the `strongswan.conf` file. ''; }; diff --git a/nixos/modules/services/networking/stunnel.nix b/nixos/modules/services/networking/stunnel.nix index af0f53567ba..3bd0367a0bb 100644 --- a/nixos/modules/services/networking/stunnel.nix +++ b/nixos/modules/services/networking/stunnel.nix @@ -77,10 +77,10 @@ in servers = mkOption { - description = '' + description = lib.mdDoc '' Define the server configuations. - See "SERVICE-LEVEL OPTIONS" in <citerefentry><refentrytitle>stunnel</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + See "SERVICE-LEVEL OPTIONS" in {manpage}`stunnel(8)`. ''; type = with types; attrsOf (attrsOf (nullOr (oneOf [bool int str]))); example = { @@ -94,12 +94,12 @@ in }; clients = mkOption { - description = '' + description = lib.mdDoc '' Define the client configurations. By default, verifyChain and OCSPaia are enabled and a CAFile is provided from pkgs.cacert. - See "SERVICE-LEVEL OPTIONS" in <citerefentry><refentrytitle>stunnel</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + See "SERVICE-LEVEL OPTIONS" in {manpage}`stunnel(8)`. ''; type = with types; attrsOf (attrsOf (nullOr (oneOf [bool int str]))); diff --git a/nixos/modules/services/networking/unbound.nix b/nixos/modules/services/networking/unbound.nix index 4f755f2af2a..5bbb0f79d57 100644 --- a/nixos/modules/services/networking/unbound.nix +++ b/nixos/modules/services/networking/unbound.nix @@ -150,9 +150,9 @@ in { remote-control.control-enable = true; }; ''; - description = '' + description = lib.mdDoc '' Declarative Unbound configuration - See the <citerefentry><refentrytitle>unbound.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> manpage for a list of + See the {manpage}`unbound.conf(5)` manpage for a list of available options. ''; }; diff --git a/nixos/modules/services/networking/wpa_supplicant.nix b/nixos/modules/services/networking/wpa_supplicant.nix index 4a163b5e022..59e408f6319 100644 --- a/nixos/modules/services/networking/wpa_supplicant.nix +++ b/nixos/modules/services/networking/wpa_supplicant.nix @@ -396,10 +396,10 @@ in { example = '' bssid_blacklist=02:11:22:33:44:55 02:22:aa:44:55:66 ''; - description = '' + description = lib.mdDoc '' Extra configuration lines appended to the network block. See - <citerefentry><refentrytitle>wpa_supplicant.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`wpa_supplicant.conf(5)` for available options. ''; }; @@ -470,10 +470,10 @@ in { example = '' p2p_disabled=1 ''; - description = '' + description = lib.mdDoc '' Extra lines appended to the configuration file. See - <citerefentry><refentrytitle>wpa_supplicant.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + {manpage}`wpa_supplicant.conf(5)` for available options. ''; }; diff --git a/nixos/modules/services/networking/znc/default.nix b/nixos/modules/services/networking/znc/default.nix index 42a332d6bf0..7ca28700dae 100644 --- a/nixos/modules/services/networking/znc/default.nix +++ b/nixos/modules/services/networking/znc/default.nix @@ -87,7 +87,7 @@ in default = "znc"; example = "john"; type = types.str; - description = '' + description = lib.mdDoc '' The name of an existing user account to use to own the ZNC server process. If not specified, a default user will be created. ''; @@ -97,7 +97,7 @@ in default = defaultUser; example = "users"; type = types.str; - description = '' + description = lib.mdDoc '' Group to own the ZNC process. ''; }; @@ -106,7 +106,7 @@ in default = "/var/lib/znc"; example = "/home/john/.znc"; type = types.path; - description = '' + description = lib.mdDoc '' The state directory for ZNC. The config and the modules will be linked to from this directory as well. ''; @@ -115,10 +115,10 @@ in openFirewall = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to open ports in the firewall for ZNC. Does work with ports for listeners specified in - <option>services.znc.config.Listener</option>. + {option}`services.znc.config.Listener`. ''; }; @@ -177,12 +177,12 @@ in configFile = mkOption { type = types.path; example = literalExpression "~/.znc/configs/znc.conf"; - description = '' + description = lib.mdDoc '' Configuration file for ZNC. It is recommended to use the - <option>config</option> option instead. + {option}`config` option instead. Setting this option will override any auto-generated config file - through the <option>confOptions</option> or <option>config</option> + through the {option}`confOptions` or {option}`config` options. ''; }; @@ -191,7 +191,7 @@ in type = types.listOf types.package; default = [ ]; example = literalExpression "[ pkgs.zncModules.fish pkgs.zncModules.push ]"; - description = '' + description = lib.mdDoc '' A list of global znc module packages to add to znc. ''; }; @@ -199,9 +199,9 @@ in mutable = mkOption { default = true; # TODO: Default to true when config is set, make sure to not delete the old config if present type = types.bool; - description = '' + description = lib.mdDoc '' Indicates whether to allow the contents of the - <literal>dataDir</literal> directory to be changed by the user at + `dataDir` directory to be changed by the user at run-time. If enabled, modifications to the ZNC configuration after its initial @@ -217,7 +217,7 @@ in default = [ ]; example = [ "--debug" ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' Extra arguments to use for executing znc. ''; }; diff --git a/nixos/modules/services/security/usbguard.nix b/nixos/modules/services/security/usbguard.nix index 8178deaf05d..24247593906 100644 --- a/nixos/modules/services/security/usbguard.nix +++ b/nixos/modules/services/security/usbguard.nix @@ -57,19 +57,19 @@ in example = '' allow with-interface equals { 08:*:* } ''; - description = '' + description = lib.mdDoc '' The USBGuard daemon will load this as the policy rule set. As these rules are NixOS managed they are immutable and can't be changed by the IPC interface. If you do not set this option, the USBGuard daemon will load - it's policy rule set from <literal>${defaultRuleFile}</literal>. + it's policy rule set from `${defaultRuleFile}`. This file can be changed manually or via the IPC interface. - Running <literal>usbguard generate-policy</literal> as root will + Running `usbguard generate-policy` as root will generate a config for your currently plugged in devices. - For more details see <citerefentry><refentrytitle>usbguard-rules.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + For more details see {manpage}`usbguard-rules.conf(5)`. ''; }; diff --git a/nixos/modules/services/system/kerberos/default.nix b/nixos/modules/services/system/kerberos/default.nix index 9a1e6739901..3ace9de5ea7 100644 --- a/nixos/modules/services/system/kerberos/default.nix +++ b/nixos/modules/services/system/kerberos/default.nix @@ -9,19 +9,19 @@ let options = { principal = mkOption { type = types.str; - description = "Which principal the rule applies to"; + description = lib.mdDoc "Which principal the rule applies to"; }; access = mkOption { type = types.either (types.listOf (types.enum ["add" "cpw" "delete" "get" "list" "modify"])) (types.enum ["all"]); default = "all"; - description = "The changes the principal is allowed to make."; + description = lib.mdDoc "The changes the principal is allowed to make."; }; target = mkOption { type = types.str; default = "*"; - description = "The principals that 'access' applies to."; + description = lib.mdDoc "The principals that 'access' applies to."; }; }; }; @@ -34,7 +34,7 @@ let { principal = "*/admin"; access = "all"; } { principal = "admin"; access = "all"; } ]; - description = '' + description = lib.mdDoc '' The privileges granted to a user. ''; }; @@ -55,7 +55,7 @@ in realms = mkOption { type = types.attrsOf (types.submodule realm); - description = '' + description = lib.mdDoc '' The realm(s) to serve keys for. ''; }; diff --git a/nixos/modules/services/system/nscd.nix b/nixos/modules/services/system/nscd.nix index 002c4092780..c3046a5b4cf 100644 --- a/nixos/modules/services/system/nscd.nix +++ b/nixos/modules/services/system/nscd.nix @@ -20,7 +20,7 @@ in enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable the Name Service Cache Daemon. Disabling this is strongly discouraged, as this effectively disables NSS Lookups from all non-glibc NSS modules, including the ones provided by systemd. @@ -30,7 +30,7 @@ in config = mkOption { type = types.lines; default = builtins.readFile ./nscd.conf; - description = "Configuration to use for Name Service Cache Daemon."; + description = lib.mdDoc "Configuration to use for Name Service Cache Daemon."; }; package = mkOption { @@ -43,7 +43,7 @@ in then pkgs.stdenv.cc.libc.bin else pkgs.glibc.bin; ''; - description = "package containing the nscd binary to be used by the service"; + description = lib.mdDoc "package containing the nscd binary to be used by the service"; }; }; diff --git a/nixos/modules/services/ttys/getty.nix b/nixos/modules/services/ttys/getty.nix index 0ff27094400..2b32aec0a73 100644 --- a/nixos/modules/services/ttys/getty.nix +++ b/nixos/modules/services/ttys/getty.nix @@ -52,13 +52,13 @@ in loginOptions = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Template for arguments to be passed to - <citerefentry><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + {manpage}`login(1)`. - See <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details, + See {manpage}`agetty(1)` for details, including security considerations. If unspecified, agetty - will not be invoked with a <option>--login-options</option> + will not be invoked with a {option}`--login-options` option. ''; example = "-h darkstar -- \\u"; diff --git a/nixos/modules/services/web-apps/bookstack.nix b/nixos/modules/services/web-apps/bookstack.nix index 5d22a3b9a8d..b939adc50fa 100644 --- a/nixos/modules/services/web-apps/bookstack.nix +++ b/nixos/modules/services/web-apps/bookstack.nix @@ -38,21 +38,21 @@ in { user = mkOption { default = "bookstack"; - description = "User bookstack runs as."; + description = lib.mdDoc "User bookstack runs as."; type = types.str; }; group = mkOption { default = "bookstack"; - description = "Group bookstack runs as."; + description = lib.mdDoc "Group bookstack runs as."; type = types.str; }; appKeyFile = mkOption { - description = '' + description = lib.mdDoc '' A file containing the Laravel APP_KEY - a 32 character long, base64 encoded key used for encryption where needed. Can be - generated with <literal>head -c 32 /dev/urandom | base64</literal>. + generated with `head -c 32 /dev/urandom | base64`. ''; example = "/run/keys/bookstack-appkey"; type = types.path; @@ -66,15 +66,15 @@ in { config.networking.hostName; defaultText = lib.literalExpression "config.networking.fqdn"; example = "bookstack.example.com"; - description = '' + description = lib.mdDoc '' The hostname to serve BookStack on. ''; }; appURL = mkOption { - description = '' + description = lib.mdDoc '' The root URL that you want to host BookStack on. All URLs in BookStack will be generated using this value. - If you change this in the future you may need to run a command to update stored URLs in the database. Command example: <literal>php artisan bookstack:update-url https://old.example.com https://new.example.com</literal> + If you change this in the future you may need to run a command to update stored URLs in the database. Command example: `php artisan bookstack:update-url https://old.example.com https://new.example.com` ''; default = "http${lib.optionalString tlsEnabled "s"}://${cfg.hostname}"; defaultText = ''http''${lib.optionalString tlsEnabled "s"}://''${cfg.hostname}''; @@ -83,7 +83,7 @@ in { }; dataDir = mkOption { - description = "BookStack data directory"; + description = lib.mdDoc "BookStack data directory"; default = "/var/lib/bookstack"; type = types.path; }; @@ -92,37 +92,37 @@ in { host = mkOption { type = types.str; default = "localhost"; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { type = types.port; default = 3306; - description = "Database host port."; + description = lib.mdDoc "Database host port."; }; name = mkOption { type = types.str; default = "bookstack"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = user; defaultText = literalExpression "user"; - description = "Database username."; + description = lib.mdDoc "Database username."; }; passwordFile = mkOption { type = with types; nullOr path; default = null; example = "/run/keys/bookstack-dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; createLocally = mkOption { type = types.bool; default = false; - description = "Create the database and database user locally."; + description = lib.mdDoc "Create the database and database user locally."; }; }; @@ -130,47 +130,47 @@ in { driver = mkOption { type = types.enum [ "smtp" "sendmail" ]; default = "smtp"; - description = "Mail driver to use."; + description = lib.mdDoc "Mail driver to use."; }; host = mkOption { type = types.str; default = "localhost"; - description = "Mail host address."; + description = lib.mdDoc "Mail host address."; }; port = mkOption { type = types.port; default = 1025; - description = "Mail host port."; + description = lib.mdDoc "Mail host port."; }; fromName = mkOption { type = types.str; default = "BookStack"; - description = "Mail \"from\" name."; + description = lib.mdDoc "Mail \"from\" name."; }; from = mkOption { type = types.str; default = "mail@bookstackapp.com"; - description = "Mail \"from\" email."; + description = lib.mdDoc "Mail \"from\" email."; }; user = mkOption { type = with types; nullOr str; default = null; example = "bookstack"; - description = "Mail username."; + description = lib.mdDoc "Mail username."; }; passwordFile = mkOption { type = with types; nullOr path; default = null; example = "/run/keys/bookstack-mailpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>mail.user</option>. + {option}`mail.user`. ''; }; encryption = mkOption { type = with types; nullOr (enum [ "tls" ]); default = null; - description = "SMTP encryption mechanism to use."; + description = lib.mdDoc "SMTP encryption mechanism to use."; }; }; @@ -178,7 +178,7 @@ in { type = types.str; default = "18M"; example = "1G"; - description = "The maximum size for uploads (e.g. images)."; + description = lib.mdDoc "The maximum size for uploads (e.g. images)."; }; poolConfig = mkOption { @@ -191,8 +191,8 @@ in { "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the bookstack PHP pool. See the documentation on <literal>php-fpm.conf</literal> + description = lib.mdDoc '' + Options for the bookstack PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; @@ -213,7 +213,7 @@ in { enableACME = true; } ''; - description = '' + description = lib.mdDoc '' With this option, you can customize the nginx virtualHost settings. ''; }; @@ -256,20 +256,20 @@ in { OIDC_ISSUER_DISCOVER = true; } ''; - description = '' + description = lib.mdDoc '' BookStack configuration options to set in the - <filename>.env</filename> file. + {file}`.env` file. - Refer to <link xlink:href="https://www.bookstackapp.com/docs/"/> + Refer to <https://www.bookstackapp.com/docs/> for details on supported values. Settings containing secret data should be set to an attribute - set containing the attribute <literal>_secret</literal> - a + set containing the attribute `_secret` - a string pointing to a file containing the value the option should be set to. See the example to get a better picture of - this: in the resulting <filename>.env</filename> file, the - <literal>OIDC_CLIENT_SECRET</literal> key will be set to the - contents of the <filename>/run/keys/oidc_secret</filename> + this: in the resulting {file}`.env` file, the + `OIDC_CLIENT_SECRET` key will be set to the + contents of the {file}`/run/keys/oidc_secret` file. ''; }; diff --git a/nixos/modules/services/web-apps/fluidd.nix b/nixos/modules/services/web-apps/fluidd.nix index 6ac1acc9d03..8d6d48b3dd2 100644 --- a/nixos/modules/services/web-apps/fluidd.nix +++ b/nixos/modules/services/web-apps/fluidd.nix @@ -10,7 +10,7 @@ in package = mkOption { type = types.package; - description = "Fluidd package to be used in the module"; + description = lib.mdDoc "Fluidd package to be used in the module"; default = pkgs.fluidd; defaultText = literalExpression "pkgs.fluidd"; }; @@ -18,7 +18,7 @@ in hostName = mkOption { type = types.str; default = "localhost"; - description = "Hostname to serve fluidd on"; + description = lib.mdDoc "Hostname to serve fluidd on"; }; nginx = mkOption { @@ -30,7 +30,7 @@ in serverAliases = [ "fluidd.''${config.networking.domain}" ]; } ''; - description = "Extra configuration for the nginx virtual host of fluidd."; + description = lib.mdDoc "Extra configuration for the nginx virtual host of fluidd."; }; }; diff --git a/nixos/modules/services/web-apps/jirafeau.nix b/nixos/modules/services/web-apps/jirafeau.nix index 328c61c8e64..c95d8ffd524 100644 --- a/nixos/modules/services/web-apps/jirafeau.nix +++ b/nixos/modules/services/web-apps/jirafeau.nix @@ -25,7 +25,7 @@ in adminPasswordSha256 = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' SHA-256 of the desired administration password. Leave blank/unset for no password. ''; }; @@ -33,7 +33,7 @@ in dataDir = mkOption { type = types.path; default = "/var/lib/jirafeau/data/"; - description = "Location of Jirafeau storage directory."; + description = lib.mdDoc "Location of Jirafeau storage directory."; }; enable = mkEnableOption "Jirafeau file upload application."; @@ -58,13 +58,13 @@ in hostName = mkOption { type = types.str; default = "localhost"; - description = "URL of instance. Must have trailing slash."; + description = lib.mdDoc "URL of instance. Must have trailing slash."; }; maxUploadSizeMegabytes = mkOption { type = types.int; default = 0; - description = "Maximum upload size of accepted files."; + description = lib.mdDoc "Maximum upload size of accepted files."; }; maxUploadTimeout = mkOption { @@ -89,14 +89,14 @@ in serverAliases = [ "wiki.''${config.networking.domain}" ]; } ''; - description = "Extra configuration for the nginx virtual host of Jirafeau."; + description = lib.mdDoc "Extra configuration for the nginx virtual host of Jirafeau."; }; package = mkOption { type = types.package; default = pkgs.jirafeau; defaultText = literalExpression "pkgs.jirafeau"; - description = "Jirafeau package to use"; + description = lib.mdDoc "Jirafeau package to use"; }; poolConfig = mkOption { @@ -109,8 +109,8 @@ in "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for Jirafeau PHP pool. See documentation on <literal>php-fpm.conf</literal> for + description = lib.mdDoc '' + Options for Jirafeau PHP pool. See documentation on `php-fpm.conf` for details on configuration directives. ''; }; diff --git a/nixos/modules/services/web-apps/limesurvey.nix b/nixos/modules/services/web-apps/limesurvey.nix index 5ccd742a303..e0995e0b5a4 100644 --- a/nixos/modules/services/web-apps/limesurvey.nix +++ b/nixos/modules/services/web-apps/limesurvey.nix @@ -39,41 +39,41 @@ in type = types.enum [ "mysql" "pgsql" "odbc" "mssql" ]; example = "pgsql"; default = "mysql"; - description = "Database engine to use."; + description = lib.mdDoc "Database engine to use."; }; host = mkOption { type = types.str; default = "localhost"; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { type = types.int; default = if cfg.database.type == "pgsql" then 5442 else 3306; defaultText = literalExpression "3306"; - description = "Database host port."; + description = lib.mdDoc "Database host port."; }; name = mkOption { type = types.str; default = "limesurvey"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = "limesurvey"; - description = "Database user."; + description = lib.mdDoc "Database user."; }; passwordFile = mkOption { type = types.nullOr types.path; default = null; example = "/run/keys/limesurvey-dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; @@ -85,14 +85,14 @@ in else null ; defaultText = literalExpression "/run/mysqld/mysqld.sock"; - description = "Path to the unix socket file to use for authentication."; + description = lib.mdDoc "Path to the unix socket file to use for authentication."; }; createLocally = mkOption { type = types.bool; default = cfg.database.type == "mysql"; defaultText = literalExpression "true"; - description = '' + description = lib.mdDoc '' Create the database and database user locally. This currently only applies if database type "mysql" is selected. ''; @@ -109,9 +109,9 @@ in enableACME = true; } ''; - description = '' - Apache configuration can be done by adapting <literal>services.httpd.virtualHosts.<name></literal>. - See <xref linkend="opt-services.httpd.virtualHosts"/> for further information. + description = lib.mdDoc '' + Apache configuration can be done by adapting `services.httpd.virtualHosts.<name>`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; @@ -125,8 +125,8 @@ in "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the LimeSurvey PHP pool. See the documentation on <literal>php-fpm.conf</literal> + description = lib.mdDoc '' + Options for the LimeSurvey PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; @@ -134,9 +134,9 @@ in config = mkOption { type = configType; default = {}; - description = '' + description = lib.mdDoc '' LimeSurvey configuration. Refer to - <link xlink:href="https://manual.limesurvey.org/Optional_settings"/> + <https://manual.limesurvey.org/Optional_settings> for details on supported values. ''; }; diff --git a/nixos/modules/services/web-apps/matomo.nix b/nixos/modules/services/web-apps/matomo.nix index c6d4ed6d39d..80c4db1263e 100644 --- a/nixos/modules/services/web-apps/matomo.nix +++ b/nixos/modules/services/web-apps/matomo.nix @@ -32,7 +32,7 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable Matomo web analytics with php-fpm backend. Either the nginx option or the webServerUser option is mandatory. ''; @@ -40,7 +40,7 @@ in { package = mkOption { type = types.package; - description = '' + description = lib.mdDoc '' Matomo package for the service to use. This can be used to point to newer releases from nixos-unstable, as they don't get backported if they are not security-relevant. @@ -64,13 +64,13 @@ in { periodicArchiveProcessing = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable periodic archive processing, which generates aggregated reports from the visits. This means that you can safely disable browser triggers for Matomo archiving, and safely enable to delete old visitor logs. Before deleting visitor logs, - make sure though that you run <literal>systemctl start matomo-archive-processing.service</literal> + make sure though that you run `systemctl start matomo-archive-processing.service` at least once without errors if you have already collected data before. ''; }; @@ -84,7 +84,7 @@ in { else "${user}.''${config.${options.networking.hostName}}" ''; example = "matomo.yourdomain.org"; - description = '' + description = lib.mdDoc '' URL of the host, without https prefix. You may want to change it if you run Matomo on a different URL than matomo.yourdomain. ''; @@ -112,12 +112,12 @@ in { enableACME = false; } ''; - description = '' + description = lib.mdDoc '' With this option, you can customize an nginx virtualHost which already has sensible defaults for Matomo. Either this option or the webServerUser option is mandatory. Set this to {} to just enable the virtualHost if you don't need any customization. - If enabled, then by default, the <option>serverName</option> is - <literal>''${user}.''${config.networking.hostName}.''${config.networking.domain}</literal>, + If enabled, then by default, the {option}`serverName` is + `''${user}.''${config.networking.hostName}.''${config.networking.domain}`, SSL is active, and certificates are acquired via ACME. If this is set to null (the default), no nginx virtualHost will be configured. ''; diff --git a/nixos/modules/services/web-apps/mediawiki.nix b/nixos/modules/services/web-apps/mediawiki.nix index 71154555942..01083eff612 100644 --- a/nixos/modules/services/web-apps/mediawiki.nix +++ b/nixos/modules/services/web-apps/mediawiki.nix @@ -177,20 +177,20 @@ in type = types.package; default = pkgs.mediawiki; defaultText = literalExpression "pkgs.mediawiki"; - description = "Which MediaWiki package to use."; + description = lib.mdDoc "Which MediaWiki package to use."; }; name = mkOption { type = types.str; default = "MediaWiki"; example = "Foobar Wiki"; - description = "Name of the wiki."; + description = lib.mdDoc "Name of the wiki."; }; uploadsDir = mkOption { type = types.nullOr types.path; default = "${stateDir}/uploads"; - description = '' + description = lib.mdDoc '' This directory is used for uploads of pictures. The directory passed here is automatically created and permissions adjusted as required. ''; @@ -198,15 +198,15 @@ in passwordFile = mkOption { type = types.path; - description = "A file containing the initial password for the admin user."; + description = lib.mdDoc "A file containing the initial password for the admin user."; example = "/run/keys/mediawiki-password"; }; skins = mkOption { default = {}; type = types.attrsOf types.path; - description = '' - Attribute set of paths whose content is copied to the <filename>skins</filename> + description = lib.mdDoc '' + Attribute set of paths whose content is copied to the {file}`skins` subdirectory of the MediaWiki installation in addition to the default skins. ''; }; @@ -214,11 +214,11 @@ in extensions = mkOption { default = {}; type = types.attrsOf (types.nullOr types.path); - description = '' - Attribute set of paths whose content is copied to the <filename>extensions</filename> + description = lib.mdDoc '' + Attribute set of paths whose content is copied to the {file}`extensions` subdirectory of the MediaWiki installation and enabled in configuration. - Use <literal>null</literal> instead of path to enable extensions that are part of MediaWiki. + Use `null` instead of path to enable extensions that are part of MediaWiki. ''; example = literalExpression '' { @@ -235,52 +235,52 @@ in type = mkOption { type = types.enum [ "mysql" "postgres" "sqlite" "mssql" "oracle" ]; default = "mysql"; - description = "Database engine to use. MySQL/MariaDB is the database of choice by MediaWiki developers."; + description = lib.mdDoc "Database engine to use. MySQL/MariaDB is the database of choice by MediaWiki developers."; }; host = mkOption { type = types.str; default = "localhost"; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { type = types.port; default = 3306; - description = "Database host port."; + description = lib.mdDoc "Database host port."; }; name = mkOption { type = types.str; default = "mediawiki"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = "mediawiki"; - description = "Database user."; + description = lib.mdDoc "Database user."; }; passwordFile = mkOption { type = types.nullOr types.path; default = null; example = "/run/keys/mediawiki-dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; tablePrefix = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' If you only have access to a single database and wish to install more than one version of MediaWiki, or have other applications that also use the database, you can give the table names a unique prefix to stop any naming conflicts or confusion. - See <link xlink:href="https://www.mediawiki.org/wiki/Manual:$wgDBprefix"/>. + See <https://www.mediawiki.org/wiki/Manual:$wgDBprefix>. ''; }; @@ -288,14 +288,14 @@ in type = types.nullOr types.path; default = if cfg.database.createLocally then "/run/mysqld/mysqld.sock" else null; defaultText = literalExpression "/run/mysqld/mysqld.sock"; - description = "Path to the unix socket file to use for authentication."; + description = lib.mdDoc "Path to the unix socket file to use for authentication."; }; createLocally = mkOption { type = types.bool; default = cfg.database.type == "mysql"; defaultText = literalExpression "true"; - description = '' + description = lib.mdDoc '' Create the database and database user locally. This currently only applies if database type "mysql" is selected. ''; @@ -312,9 +312,9 @@ in enableACME = true; } ''; - description = '' - Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>. - See <xref linkend="opt-services.httpd.virtualHosts"/> for further information. + description = lib.mdDoc '' + Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; @@ -328,18 +328,18 @@ in "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the MediaWiki PHP pool. See the documentation on <literal>php-fpm.conf</literal> + description = lib.mdDoc '' + Options for the MediaWiki PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; extraConfig = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' Any additional text to be appended to MediaWiki's LocalSettings.php configuration file. For configuration - settings, see <link xlink:href="https://www.mediawiki.org/wiki/Manual:Configuration_settings"/>. + settings, see <https://www.mediawiki.org/wiki/Manual:Configuration_settings>. ''; default = ""; example = '' diff --git a/nixos/modules/services/web-apps/moodle.nix b/nixos/modules/services/web-apps/moodle.nix index 55e5ac9281e..6d1a9839ca1 100644 --- a/nixos/modules/services/web-apps/moodle.nix +++ b/nixos/modules/services/web-apps/moodle.nix @@ -68,13 +68,13 @@ in type = types.package; default = pkgs.moodle; defaultText = literalExpression "pkgs.moodle"; - description = "The Moodle package to use."; + description = lib.mdDoc "The Moodle package to use."; }; initialPassword = mkOption { type = types.str; example = "correcthorsebatterystaple"; - description = '' + description = lib.mdDoc '' Specifies the initial password for the admin, i.e. the password assigned if the user does not already exist. The password specified here is world-readable in the Nix store, so it should be changed promptly. ''; @@ -84,18 +84,18 @@ in type = mkOption { type = types.enum [ "mysql" "pgsql" ]; default = "mysql"; - description = "Database engine to use."; + description = lib.mdDoc "Database engine to use."; }; host = mkOption { type = types.str; default = "localhost"; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { type = types.int; - description = "Database host port."; + description = lib.mdDoc "Database host port."; default = { mysql = 3306; pgsql = 5432; @@ -106,22 +106,22 @@ in name = mkOption { type = types.str; default = "moodle"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = "moodle"; - description = "Database user."; + description = lib.mdDoc "Database user."; }; passwordFile = mkOption { type = types.nullOr types.path; default = null; example = "/run/keys/moodle-dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; @@ -132,7 +132,7 @@ in else if pgsqlLocal then "/run/postgresql" else null; defaultText = literalExpression "/run/mysqld/mysqld.sock"; - description = "Path to the unix socket file to use for authentication."; + description = lib.mdDoc "Path to the unix socket file to use for authentication."; }; createLocally = mkOption { @@ -152,9 +152,9 @@ in enableACME = true; } ''; - description = '' - Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>. - See <xref linkend="opt-services.httpd.virtualHosts"/> for further information. + description = lib.mdDoc '' + Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; @@ -168,8 +168,8 @@ in "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the Moodle PHP pool. See the documentation on <literal>php-fpm.conf</literal> + description = lib.mdDoc '' + Options for the Moodle PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; @@ -177,10 +177,10 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Any additional text to be appended to the config.php configuration file. This is a PHP script. For configuration - details, see <link xlink:href="https://docs.moodle.org/37/en/Configuration_file"/>. + details, see <https://docs.moodle.org/37/en/Configuration_file>. ''; example = '' $CFG->disableupdatenotifications = true; diff --git a/nixos/modules/services/web-apps/snipe-it.nix b/nixos/modules/services/web-apps/snipe-it.nix index 3059e67cb43..2eda0c7690a 100644 --- a/nixos/modules/services/web-apps/snipe-it.nix +++ b/nixos/modules/services/web-apps/snipe-it.nix @@ -32,21 +32,21 @@ in { user = mkOption { default = "snipeit"; - description = "User snipe-it runs as."; + description = lib.mdDoc "User snipe-it runs as."; type = types.str; }; group = mkOption { default = "snipeit"; - description = "Group snipe-it runs as."; + description = lib.mdDoc "Group snipe-it runs as."; type = types.str; }; appKeyFile = mkOption { - description = '' + description = lib.mdDoc '' A file containing the Laravel APP_KEY - a 32 character long, base64 encoded key used for encryption where needed. Can be - generated with <literal>head -c 32 /dev/urandom | base64</literal>. + generated with `head -c 32 /dev/urandom | base64`. ''; example = "/run/keys/snipe-it/appkey"; type = types.path; @@ -60,16 +60,16 @@ in { config.networking.hostName; defaultText = lib.literalExpression "config.networking.fqdn"; example = "snipe-it.example.com"; - description = '' + description = lib.mdDoc '' The hostname to serve Snipe-IT on. ''; }; appURL = mkOption { - description = '' + description = lib.mdDoc '' The root URL that you want to host Snipe-IT on. All URLs in Snipe-IT will be generated using this value. If you change this in the future you may need to run a command to update stored URLs in the database. - Command example: <literal>snipe-it snipe-it:update-url https://old.example.com https://new.example.com</literal> + Command example: `snipe-it snipe-it:update-url https://old.example.com https://new.example.com` ''; default = "http${lib.optionalString tlsEnabled "s"}://${cfg.hostName}"; defaultText = '' @@ -80,7 +80,7 @@ in { }; dataDir = mkOption { - description = "snipe-it data directory"; + description = lib.mdDoc "snipe-it data directory"; default = "/var/lib/snipe-it"; type = types.path; }; @@ -89,37 +89,37 @@ in { host = mkOption { type = types.str; default = "localhost"; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { type = types.port; default = 3306; - description = "Database host port."; + description = lib.mdDoc "Database host port."; }; name = mkOption { type = types.str; default = "snipeit"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = user; defaultText = literalExpression "user"; - description = "Database username."; + description = lib.mdDoc "Database username."; }; passwordFile = mkOption { type = with types; nullOr path; default = null; example = "/run/keys/snipe-it/dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; createLocally = mkOption { type = types.bool; default = false; - description = "Create the database and database user locally."; + description = lib.mdDoc "Create the database and database user locally."; }; }; @@ -127,65 +127,65 @@ in { driver = mkOption { type = types.enum [ "smtp" "sendmail" ]; default = "smtp"; - description = "Mail driver to use."; + description = lib.mdDoc "Mail driver to use."; }; host = mkOption { type = types.str; default = "localhost"; - description = "Mail host address."; + description = lib.mdDoc "Mail host address."; }; port = mkOption { type = types.port; default = 1025; - description = "Mail host port."; + description = lib.mdDoc "Mail host port."; }; encryption = mkOption { type = with types; nullOr (enum [ "tls" "ssl" ]); default = null; - description = "SMTP encryption mechanism to use."; + description = lib.mdDoc "SMTP encryption mechanism to use."; }; user = mkOption { type = with types; nullOr str; default = null; example = "snipeit"; - description = "Mail username."; + description = lib.mdDoc "Mail username."; }; passwordFile = mkOption { type = with types; nullOr path; default = null; example = "/run/keys/snipe-it/mailpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>mail.user</option>. + {option}`mail.user`. ''; }; backupNotificationAddress = mkOption { type = types.str; default = "backup@example.com"; - description = "Email Address to send Backup Notifications to."; + description = lib.mdDoc "Email Address to send Backup Notifications to."; }; from = { name = mkOption { type = types.str; default = "Snipe-IT Asset Management"; - description = "Mail \"from\" name."; + description = lib.mdDoc "Mail \"from\" name."; }; address = mkOption { type = types.str; default = "mail@example.com"; - description = "Mail \"from\" address."; + description = lib.mdDoc "Mail \"from\" address."; }; }; replyTo = { name = mkOption { type = types.str; default = "Snipe-IT Asset Management"; - description = "Mail \"reply-to\" name."; + description = lib.mdDoc "Mail \"reply-to\" name."; }; address = mkOption { type = types.str; default = "mail@example.com"; - description = "Mail \"reply-to\" address."; + description = lib.mdDoc "Mail \"reply-to\" address."; }; }; }; @@ -194,7 +194,7 @@ in { type = types.str; default = "18M"; example = "1G"; - description = "The maximum size for uploads (e.g. images)."; + description = lib.mdDoc "The maximum size for uploads (e.g. images)."; }; poolConfig = mkOption { @@ -207,8 +207,8 @@ in { "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the snipe-it PHP pool. See the documentation on <literal>php-fpm.conf</literal> + description = lib.mdDoc '' + Options for the snipe-it PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; @@ -229,7 +229,7 @@ in { enableACME = true; } ''; - description = '' + description = lib.mdDoc '' With this option, you can customize the nginx virtualHost settings. ''; }; @@ -272,19 +272,19 @@ in { OIDC_ISSUER_DISCOVER = true; } ''; - description = '' + description = lib.mdDoc '' Snipe-IT configuration options to set in the - <filename>.env</filename> file. - Refer to <link xlink:href="https://snipe-it.readme.io/docs/configuration"/> + {file}`.env` file. + Refer to <https://snipe-it.readme.io/docs/configuration> for details on supported values. Settings containing secret data should be set to an attribute - set containing the attribute <literal>_secret</literal> - a + set containing the attribute `_secret` - a string pointing to a file containing the value the option should be set to. See the example to get a better picture of - this: in the resulting <filename>.env</filename> file, the - <literal>OIDC_CLIENT_SECRET</literal> key will be set to the - contents of the <filename>/run/keys/oidc_secret</filename> + this: in the resulting {file}`.env` file, the + `OIDC_CLIENT_SECRET` key will be set to the + contents of the {file}`/run/keys/oidc_secret` file. ''; }; diff --git a/nixos/modules/services/web-apps/wordpress.nix b/nixos/modules/services/web-apps/wordpress.nix index b1ae4deb276..c841ded353e 100644 --- a/nixos/modules/services/web-apps/wordpress.nix +++ b/nixos/modules/services/web-apps/wordpress.nix @@ -82,13 +82,13 @@ let type = types.package; default = pkgs.wordpress; defaultText = literalExpression "pkgs.wordpress"; - description = "Which WordPress package to use."; + description = lib.mdDoc "Which WordPress package to use."; }; uploadsDir = mkOption { type = types.path; default = "/var/lib/wordpress/${name}/uploads"; - description = '' + description = lib.mdDoc '' This directory is used for uploads of pictures. The directory passed here is automatically created and permissions adjusted as required. ''; @@ -152,47 +152,47 @@ let host = mkOption { type = types.str; default = "localhost"; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { type = types.port; default = 3306; - description = "Database host port."; + description = lib.mdDoc "Database host port."; }; name = mkOption { type = types.str; default = "wordpress"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = "wordpress"; - description = "Database user."; + description = lib.mdDoc "Database user."; }; passwordFile = mkOption { type = types.nullOr types.path; default = null; example = "/run/keys/wordpress-dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; tablePrefix = mkOption { type = types.str; default = "wp_"; - description = '' + description = lib.mdDoc '' The $table_prefix is the value placed in the front of your database tables. Change the value if you want to use something other than wp_ for your database prefix. Typically this is changed if you are installing multiple WordPress blogs in the same database. - See <link xlink:href="https://codex.wordpress.org/Editing_wp-config.php#table_prefix"/>. + See <https://codex.wordpress.org/Editing_wp-config.php#table_prefix>. ''; }; @@ -200,13 +200,13 @@ let type = types.nullOr types.path; default = null; defaultText = literalExpression "/run/mysqld/mysqld.sock"; - description = "Path to the unix socket file to use for authentication."; + description = lib.mdDoc "Path to the unix socket file to use for authentication."; }; createLocally = mkOption { type = types.bool; default = true; - description = "Create the database and database user locally."; + description = lib.mdDoc "Create the database and database user locally."; }; }; @@ -219,8 +219,8 @@ let enableACME = true; } ''; - description = '' - Apache configuration can be done by adapting <option>services.httpd.virtualHosts</option>. + description = lib.mdDoc '' + Apache configuration can be done by adapting {option}`services.httpd.virtualHosts`. ''; }; @@ -234,8 +234,8 @@ let "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the WordPress PHP pool. See the documentation on <literal>php-fpm.conf</literal> + description = lib.mdDoc '' + Options for the WordPress PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; @@ -243,10 +243,10 @@ let extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Any additional text to be appended to the wp-config.php configuration file. This is a PHP script. For configuration - settings, see <link xlink:href="https://codex.wordpress.org/Editing_wp-config.php"/>. + settings, see <https://codex.wordpress.org/Editing_wp-config.php>. ''; example = '' define( 'AUTOSAVE_INTERVAL', 60 ); // Seconds @@ -265,20 +265,20 @@ in sites = mkOption { type = types.attrsOf (types.submodule siteOpts); default = {}; - description = "Specification of one or more WordPress sites to serve"; + description = lib.mdDoc "Specification of one or more WordPress sites to serve"; }; webserver = mkOption { type = types.enum [ "httpd" "nginx" "caddy" ]; default = "httpd"; - description = '' + description = lib.mdDoc '' Whether to use apache2 or nginx for virtual host management. - Further nginx configuration can be done by adapting <literal>services.nginx.virtualHosts.<name></literal>. - See <xref linkend="opt-services.nginx.virtualHosts"/> for further information. + Further nginx configuration can be done by adapting `services.nginx.virtualHosts.<name>`. + See [](#opt-services.nginx.virtualHosts) for further information. - Further apache2 configuration can be done by adapting <literal>services.httpd.virtualHosts.<name></literal>. - See <xref linkend="opt-services.httpd.virtualHosts"/> for further information. + Further apache2 configuration can be done by adapting `services.httpd.virtualHosts.<name>`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; diff --git a/nixos/modules/services/web-apps/zabbix.nix b/nixos/modules/services/web-apps/zabbix.nix index 538dac0d5be..c6ac809a73b 100644 --- a/nixos/modules/services/web-apps/zabbix.nix +++ b/nixos/modules/services/web-apps/zabbix.nix @@ -46,19 +46,19 @@ in type = types.package; default = pkgs.zabbix.web; defaultText = literalExpression "zabbix.web"; - description = "Which Zabbix package to use."; + description = lib.mdDoc "Which Zabbix package to use."; }; server = { port = mkOption { type = types.int; - description = "The port of the Zabbix server to connect to."; + description = lib.mdDoc "The port of the Zabbix server to connect to."; default = 10051; }; address = mkOption { type = types.str; - description = "The IP address or hostname of the Zabbix server to connect to."; + description = lib.mdDoc "The IP address or hostname of the Zabbix server to connect to."; default = "localhost"; }; }; @@ -68,13 +68,13 @@ in type = types.enum [ "mysql" "pgsql" "oracle" ]; example = "mysql"; default = "pgsql"; - description = "Database engine to use."; + description = lib.mdDoc "Database engine to use."; }; host = mkOption { type = types.str; default = ""; - description = "Database host address."; + description = lib.mdDoc "Database host address."; }; port = mkOption { @@ -88,28 +88,28 @@ in else if config.${opt.database.type} == "pgsql" then config.${options.services.postgresql.port} else 1521 ''; - description = "Database host port."; + description = lib.mdDoc "Database host port."; }; name = mkOption { type = types.str; default = "zabbix"; - description = "Database name."; + description = lib.mdDoc "Database name."; }; user = mkOption { type = types.str; default = "zabbix"; - description = "Database user."; + description = lib.mdDoc "Database user."; }; passwordFile = mkOption { type = types.nullOr types.path; default = null; example = "/run/keys/zabbix-dbpassword"; - description = '' + description = lib.mdDoc '' A file containing the password corresponding to - <option>database.user</option>. + {option}`database.user`. ''; }; @@ -117,7 +117,7 @@ in type = types.nullOr types.path; default = null; example = "/run/postgresql"; - description = "Path to the unix socket file to use for authentication."; + description = lib.mdDoc "Path to the unix socket file to use for authentication."; }; }; @@ -131,9 +131,9 @@ in enableACME = true; } ''; - description = '' - Apache configuration can be done by adapting <literal>services.httpd.virtualHosts.<name></literal>. - See <xref linkend="opt-services.httpd.virtualHosts"/> for further information. + description = lib.mdDoc '' + Apache configuration can be done by adapting `services.httpd.virtualHosts.<name>`. + See [](#opt-services.httpd.virtualHosts) for further information. ''; }; @@ -147,16 +147,16 @@ in "pm.max_spare_servers" = 4; "pm.max_requests" = 500; }; - description = '' - Options for the Zabbix PHP pool. See the documentation on <literal>php-fpm.conf</literal> for details on configuration directives. + description = lib.mdDoc '' + Options for the Zabbix PHP pool. See the documentation on `php-fpm.conf` for details on configuration directives. ''; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Additional configuration to be copied verbatim into <filename>zabbix.conf.php</filename>. + description = lib.mdDoc '' + Additional configuration to be copied verbatim into {file}`zabbix.conf.php`. ''; }; diff --git a/nixos/modules/services/web-servers/apache-httpd/default.nix b/nixos/modules/services/web-servers/apache-httpd/default.nix index 3099705acbe..a8c9fe26369 100644 --- a/nixos/modules/services/web-servers/apache-httpd/default.nix +++ b/nixos/modules/services/web-servers/apache-httpd/default.nix @@ -410,7 +410,7 @@ in type = types.package; default = pkgs.apacheHttpd; defaultText = literalExpression "pkgs.apacheHttpd"; - description = '' + description = lib.mdDoc '' Overridable attribute of the Apache HTTP Server package to use. ''; }; @@ -420,7 +420,7 @@ in default = confFile; defaultText = literalExpression "confFile"; example = literalExpression ''pkgs.writeText "httpd.conf" "# my custom config file ..."''; - description = '' + description = lib.mdDoc '' Override the configuration file used by Apache. By default, NixOS generates one automatically. ''; @@ -429,10 +429,10 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration lines appended to the generated Apache configuration file. Note that this mechanism will not work - when <option>configFile</option> is overridden. + when {option}`configFile` is overridden. ''; }; @@ -457,27 +457,27 @@ in adminAddr = mkOption { type = types.str; example = "admin@example.org"; - description = "E-mail address of the server administrator."; + description = lib.mdDoc "E-mail address of the server administrator."; }; logFormat = mkOption { type = types.str; default = "common"; example = "combined"; - description = '' + description = lib.mdDoc '' Log format for log files. Possible values are: combined, common, referer, agent, none. - See <link xlink:href="https://httpd.apache.org/docs/2.4/logs.html"/> for more details. + See <https://httpd.apache.org/docs/2.4/logs.html> for more details. ''; }; logPerVirtualHost = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' If enabled, each virtual host gets its own - <filename>access.log</filename> and - <filename>error.log</filename>, namely suffixed by the - <option>hostName</option> of the virtual host. + {file}`access.log` and + {file}`error.log`, namely suffixed by the + {option}`hostName` of the virtual host. ''; }; @@ -498,7 +498,7 @@ in group = mkOption { type = types.str; default = "wwwrun"; - description = '' + description = lib.mdDoc '' Group under which httpd children processes run. ''; }; @@ -506,7 +506,7 @@ in logDir = mkOption { type = types.path; default = "/var/log/httpd"; - description = '' + description = lib.mdDoc '' Directory for Apache's log files. It is created automatically. ''; }; @@ -537,7 +537,7 @@ in }; } ''; - description = '' + description = lib.mdDoc '' Specification of the virtual hosts served by Apache. Each element should be an attribute set specifying the configuration of the virtual host. @@ -547,20 +547,20 @@ in enableMellon = mkOption { type = types.bool; default = false; - description = "Whether to enable the mod_auth_mellon module."; + description = lib.mdDoc "Whether to enable the mod_auth_mellon module."; }; enablePHP = mkOption { type = types.bool; default = false; - description = "Whether to enable the PHP module."; + description = lib.mdDoc "Whether to enable the PHP module."; }; phpPackage = mkOption { type = types.package; default = pkgs.php; defaultText = literalExpression "pkgs.php"; - description = '' + description = lib.mdDoc '' Overridable attribute of the PHP package to use. ''; }; @@ -568,7 +568,7 @@ in enablePerl = mkOption { type = types.bool; default = false; - description = "Whether to enable the Perl module (mod_perl)."; + description = lib.mdDoc "Whether to enable the Perl module (mod_perl)."; }; phpOptions = mkOption { @@ -578,8 +578,8 @@ in '' date.timezone = "CET" ''; - description = '' - Options appended to the PHP configuration file <filename>php.ini</filename>. + description = lib.mdDoc '' + Options appended to the PHP configuration file {file}`php.ini`. ''; }; @@ -588,13 +588,13 @@ in default = "event"; example = "worker"; description = - '' + lib.mdDoc '' Multi-processing module to be used by Apache. Available - modules are <literal>prefork</literal> (handles each - request in a separate child process), <literal>worker</literal> + modules are `prefork` (handles each + request in a separate child process), `worker` (hybrid approach that starts a number of child processes - each running a number of threads) and <literal>event</literal> - (the default; a recent variant of <literal>worker</literal> + each running a number of threads) and `event` + (the default; a recent variant of `worker` that handles persistent connections more efficiently). ''; }; @@ -603,14 +603,14 @@ in type = types.int; default = 150; example = 8; - description = "Maximum number of httpd processes (prefork)"; + description = lib.mdDoc "Maximum number of httpd processes (prefork)"; }; maxRequestsPerChild = mkOption { type = types.int; default = 0; example = 500; - description = '' + description = lib.mdDoc '' Maximum number of httpd requests answered per httpd child (prefork), 0 means unlimited. ''; }; @@ -618,14 +618,14 @@ in sslCiphers = mkOption { type = types.str; default = "HIGH:!aNULL:!MD5:!EXP"; - description = "Cipher Suite available for negotiation in SSL proxy handshake."; + description = lib.mdDoc "Cipher Suite available for negotiation in SSL proxy handshake."; }; sslProtocols = mkOption { type = types.str; default = "All -SSLv2 -SSLv3 -TLSv1 -TLSv1.1"; example = "All -SSLv2 -SSLv3"; - description = "Allowed SSL/TLS protocol versions."; + description = lib.mdDoc "Allowed SSL/TLS protocol versions."; }; }; 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 559210a1418..4f84cad7351 100644 --- a/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix +++ b/nixos/modules/services/web-servers/apache-httpd/vhost-options.nix @@ -8,14 +8,14 @@ in hostName = mkOption { type = types.str; default = name; - description = "Canonical hostname for the server."; + description = lib.mdDoc "Canonical hostname for the server."; }; serverAliases = mkOption { type = types.listOf types.str; default = []; example = ["www.example.org" "www.example.org:8080" "example.org"]; - description = '' + description = lib.mdDoc '' Additional names of virtual hosts served by this virtual host configuration. ''; }; @@ -25,17 +25,17 @@ in options = { port = mkOption { type = types.port; - description = "Port to listen on"; + description = lib.mdDoc "Port to listen on"; }; ip = mkOption { type = types.str; default = "*"; - description = "IP to listen on. 0.0.0.0 for IPv4 only, * for all."; + description = lib.mdDoc "IP to listen on. 0.0.0.0 for IPv4 only, * for all."; }; ssl = mkOption { type = types.bool; default = false; - description = "Whether to enable SSL (https) support."; + description = lib.mdDoc "Whether to enable SSL (https) support."; }; }; })); @@ -61,9 +61,9 @@ in listenAddresses = mkOption { type = with types; nonEmptyListOf str; - description = '' + description = lib.mdDoc '' Listen addresses for this virtual host. - Compared to <literal>listen</literal> this only sets the addreses + Compared to `listen` this only sets the addreses and the ports are chosen automatically. ''; default = [ "*" ]; @@ -79,9 +79,9 @@ in addSSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable HTTPS in addition to plain HTTP. This will set defaults for - <literal>listen</literal> to listen on all interfaces on the respective default + `listen` to listen on all interfaces on the respective default ports (80, 443). ''; }; @@ -89,19 +89,19 @@ in onlySSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable HTTPS and reject plain HTTP connections. This will set - defaults for <literal>listen</literal> to listen on all interfaces on port 443. + defaults for `listen` to listen on all interfaces on port 443. ''; }; forceSSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to add a separate nginx server block that permanently redirects (301) all plain HTTP traffic to HTTPS. This will set defaults for - <literal>listen</literal> to listen on all interfaces on the respective default + `listen` to listen on all interfaces on the respective default ports (80, 443), where the non-SSL listens are used for the redirect vhosts. ''; }; @@ -109,9 +109,9 @@ in enableACME = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to ask Let's Encrypt to sign a certificate for this vhost. - Alternately, you can use an existing certificate through <option>useACMEHost</option>. + Alternately, you can use an existing certificate through {option}`useACMEHost`. ''; }; @@ -130,7 +130,7 @@ in acmeRoot = mkOption { type = types.nullOr types.str; default = "/var/lib/acme/acme-challenge"; - description = '' + description = lib.mdDoc '' Directory for the acme challenge which is PUBLIC, don't put certs or keys in here. Set to null to inherit from config.security.acme. ''; @@ -139,28 +139,28 @@ in sslServerCert = mkOption { type = types.path; example = "/var/host.cert"; - description = "Path to server SSL certificate."; + description = lib.mdDoc "Path to server SSL certificate."; }; sslServerKey = mkOption { type = types.path; example = "/var/host.key"; - description = "Path to server SSL certificate key."; + description = lib.mdDoc "Path to server SSL certificate key."; }; sslServerChain = mkOption { type = types.nullOr types.path; default = null; example = "/var/ca.pem"; - description = "Path to server SSL chain file."; + description = lib.mdDoc "Path to server SSL chain file."; }; http2 = mkOption { type = types.bool; default = true; - description = '' - Whether to enable HTTP 2. HTTP/2 is supported in all multi-processing modules that come with httpd. <emphasis>However, if you use the prefork mpm, there will - be severe restrictions.</emphasis> Refer to <link xlink:href="https://httpd.apache.org/docs/2.4/howto/http2.html#mpm-config"/> for details. + description = lib.mdDoc '' + Whether to enable HTTP 2. HTTP/2 is supported in all multi-processing modules that come with httpd. *However, if you use the prefork mpm, there will + be severe restrictions.* Refer to <https://httpd.apache.org/docs/2.4/howto/http2.html#mpm-config> for details. ''; }; @@ -168,14 +168,14 @@ in type = types.nullOr types.str; default = null; example = "admin@example.org"; - description = "E-mail address of the server administrator."; + description = lib.mdDoc "E-mail address of the server administrator."; }; documentRoot = mkOption { type = types.nullOr types.path; default = null; example = "/data/webserver/docs"; - description = '' + description = lib.mdDoc '' The path of Apache's document root directory. If left undefined, an empty directory in the Nix store will be used as root. ''; @@ -189,7 +189,7 @@ in dir = "/home/eelco/Dev/nix-homepage"; } ]; - description = '' + description = lib.mdDoc '' This option provides a simple way to serve static directories. ''; }; @@ -222,7 +222,7 @@ in AllowOverride All </Directory> ''; - description = '' + description = lib.mdDoc '' These lines go to httpd.conf verbatim. They will go after directories and directory aliases defined by default. ''; @@ -231,9 +231,9 @@ in enableUserDir = mkOption { type = types.bool; default = false; - description = '' - Whether to enable serving <filename>~/public_html</filename> as - <literal>/~«username»</literal>. + description = lib.mdDoc '' + Whether to enable serving {file}`~/public_html` as + `/~«username»`. ''; }; @@ -241,7 +241,7 @@ in type = types.nullOr types.str; default = null; example = "http://newserver.example.org/"; - description = '' + description = lib.mdDoc '' If set, all requests for this host are redirected permanently to the given URL. ''; @@ -251,7 +251,7 @@ in type = types.str; default = "common"; example = "combined"; - description = '' + description = lib.mdDoc '' Log format for Apache's log files. Possible values are: combined, common, referer, agent. ''; }; @@ -260,8 +260,8 @@ in type = types.lines; default = ""; example = "Disallow: /foo/"; - description = '' - Specification of pages to be ignored by web crawlers. See <link xlink:href="http://www.robotstxt.org/"/> for details. + description = lib.mdDoc '' + Specification of pages to be ignored by web crawlers. See <http://www.robotstxt.org/> for details. ''; }; @@ -278,8 +278,8 @@ in }; }; ''; - description = '' - Declarative location config. See <link xlink:href="https://httpd.apache.org/docs/2.4/mod/core.html#location"/> for details. + description = lib.mdDoc '' + Declarative location config. See <https://httpd.apache.org/docs/2.4/mod/core.html#location> for details. ''; }; diff --git a/nixos/modules/services/web-servers/caddy/default.nix b/nixos/modules/services/web-servers/caddy/default.nix index b262313577f..7f6bc3c4a4d 100644 --- a/nixos/modules/services/web-servers/caddy/default.nix +++ b/nixos/modules/services/web-servers/caddy/default.nix @@ -86,7 +86,7 @@ in default = pkgs.caddy; defaultText = literalExpression "pkgs.caddy"; type = types.package; - description = '' + description = lib.mdDoc '' Caddy package to use. ''; }; @@ -133,9 +133,9 @@ in example = literalExpression '' mkForce "level INFO"; ''; - description = '' + description = lib.mdDoc '' Configuration for the default logger. See - <link xlink:href="https://caddyserver.com/docs/caddyfile/options#log"/> + <https://caddyserver.com/docs/caddyfile/options#log> for details. ''; }; @@ -153,7 +153,7 @@ in file_server '''; ''; - description = '' + description = lib.mdDoc '' Override the configuration file used by Caddy. By default, NixOS generates one automatically. ''; @@ -178,8 +178,8 @@ in resume = mkOption { default = false; type = types.bool; - description = '' - Use saved config, if any (and prefer over any specified configuration passed with <literal>--config</literal>). + description = lib.mdDoc '' + Use saved config, if any (and prefer over any specified configuration passed with `--config`). ''; }; @@ -194,11 +194,11 @@ in } } ''; - description = '' + description = lib.mdDoc '' Additional lines of configuration appended to the global config section - of the <literal>Caddyfile</literal>. + of the `Caddyfile`. - Refer to <link xlink:href="https://caddyserver.com/docs/caddyfile/options#global-options"/> + Refer to <https://caddyserver.com/docs/caddyfile/options#global-options> for details on supported values. ''; }; @@ -213,9 +213,9 @@ in root /srv/http } ''; - description = '' + description = lib.mdDoc '' Additional lines of configuration appended to the automatically - generated <literal>Caddyfile</literal>. + generated `Caddyfile`. ''; }; @@ -233,7 +233,7 @@ in }; }; ''; - description = '' + description = lib.mdDoc '' Declarative specification of virtual hosts served by Caddy. ''; }; @@ -242,11 +242,11 @@ in default = "https://acme-v02.api.letsencrypt.org/directory"; example = "https://acme-staging-v02.api.letsencrypt.org/directory"; type = with types; nullOr str; - description = '' + description = lib.mdDoc '' The URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's staging endpoint for testing or development. - Set it to <literal>null</literal> if you want to write a more + Set it to `null` if you want to write a more fine-grained configuration manually. ''; }; @@ -254,7 +254,7 @@ in email = mkOption { default = null; type = with types; nullOr str; - description = '' + description = lib.mdDoc '' Your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates. diff --git a/nixos/modules/services/web-servers/caddy/vhost-options.nix b/nixos/modules/services/web-servers/caddy/vhost-options.nix index f240ec605c2..ed4902b0372 100644 --- a/nixos/modules/services/web-servers/caddy/vhost-options.nix +++ b/nixos/modules/services/web-servers/caddy/vhost-options.nix @@ -9,21 +9,21 @@ in hostName = mkOption { type = types.str; default = name; - description = "Canonical hostname for the server."; + description = lib.mdDoc "Canonical hostname for the server."; }; serverAliases = mkOption { type = with types; listOf str; default = [ ]; example = [ "www.example.org" "example.org" ]; - description = '' + description = lib.mdDoc '' Additional names of virtual hosts served by this virtual host configuration. ''; }; listenAddresses = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' A list of host interfaces to bind to for this virtual host. ''; default = [ ]; @@ -59,9 +59,9 @@ in output discard '''; ''; - description = '' + description = lib.mdDoc '' Configuration for HTTP request logging (also known as access logs). See - <link xlink:href="https://caddyserver.com/docs/caddyfile/directives/log#log"/> + <https://caddyserver.com/docs/caddyfile/directives/log#log> for details. ''; }; @@ -69,9 +69,9 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional lines of configuration appended to this virtual host in the - automatically generated <literal>Caddyfile</literal>. + automatically generated `Caddyfile`. ''; }; diff --git a/nixos/modules/services/web-servers/hydron.nix b/nixos/modules/services/web-servers/hydron.nix index c2bd1baeace..292493c4c7b 100644 --- a/nixos/modules/services/web-servers/hydron.nix +++ b/nixos/modules/services/web-servers/hydron.nix @@ -17,11 +17,11 @@ in with lib; { type = types.str; default = "weekly"; example = "06:00"; - description = '' + description = lib.mdDoc '' How often we run hydron import and possibly fetch tags. Runs by default every week. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/services/web-servers/nginx/default.nix b/nixos/modules/services/web-servers/nginx/default.nix index 166f38f9ea2..72b91c37f8a 100644 --- a/nixos/modules/services/web-servers/nginx/default.nix +++ b/nixos/modules/services/web-servers/nginx/default.nix @@ -464,10 +464,10 @@ in default = []; type = types.listOf (types.attrsOf types.anything); example = literalExpression "[ pkgs.nginxModules.brotli ]"; - description = '' - Additional <link xlink:href="https://www.nginx.com/resources/wiki/modules/">third-party nginx modules</link> + description = lib.mdDoc '' + Additional [third-party nginx modules](https://www.nginx.com/resources/wiki/modules/) to install. Packaged modules are available in - <literal>pkgs.nginxModules</literal>. + `pkgs.nginxModules`. ''; }; @@ -520,12 +520,12 @@ in appendConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration lines appended to the generated Nginx configuration file. Commonly used by different modules - providing http snippets. <option>appendConfig</option> + providing http snippets. {option}`appendConfig` can be specified more than once and it's value will be - concatenated (contrary to <option>config</option> which + concatenated (contrary to {option}`config` which can be set only once). ''; }; @@ -540,7 +540,7 @@ in '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent"'; ''; - description = '' + description = lib.mdDoc '' With nginx you must provide common http context definitions before they are used, e.g. log_format, resolver, etc. inside of server or location contexts. Use this attribute to set these definitions @@ -577,7 +577,7 @@ in eventsConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration lines to be set inside the events block. ''; }; @@ -605,52 +605,52 @@ in user = mkOption { type = types.str; default = "nginx"; - description = "User account under which nginx runs."; + description = lib.mdDoc "User account under which nginx runs."; }; group = mkOption { type = types.str; default = "nginx"; - description = "Group account under which nginx runs."; + description = lib.mdDoc "Group account under which nginx runs."; }; serverTokens = mkOption { type = types.bool; default = false; - description = "Show nginx version in headers and error pages."; + description = lib.mdDoc "Show nginx version in headers and error pages."; }; clientMaxBodySize = mkOption { type = types.str; default = "10m"; - description = "Set nginx global client_max_body_size."; + description = lib.mdDoc "Set nginx global client_max_body_size."; }; sslCiphers = mkOption { type = types.nullOr types.str; # Keep in sync with https://ssl-config.mozilla.org/#server=nginx&config=intermediate default = "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384"; - description = "Ciphers to choose from when negotiating TLS handshakes."; + description = lib.mdDoc "Ciphers to choose from when negotiating TLS handshakes."; }; sslProtocols = mkOption { type = types.str; default = "TLSv1.2 TLSv1.3"; example = "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"; - description = "Allowed TLS protocol versions."; + description = lib.mdDoc "Allowed TLS protocol versions."; }; sslDhparam = mkOption { type = types.nullOr types.path; default = null; example = "/path/to/dhparams.pem"; - description = "Path to DH parameters file."; + description = lib.mdDoc "Path to DH parameters file."; }; proxyResolveWhileRunning = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Resolves domains of proxyPass targets at runtime and not only at start, you have to set services.nginx.resolver, too. @@ -660,7 +660,7 @@ in mapHashBucketSize = mkOption { type = types.nullOr (types.enum [ 32 64 128 ]); default = null; - description = '' + description = lib.mdDoc '' Sets the bucket size for the map variables hash tables. Default value depends on the processor’s cache line size. ''; @@ -669,7 +669,7 @@ in mapHashMaxSize = mkOption { type = types.nullOr types.ints.positive; default = null; - description = '' + description = lib.mdDoc '' Sets the maximum size of the map variables hash tables. ''; }; @@ -677,7 +677,7 @@ in serverNamesHashBucketSize = mkOption { type = types.nullOr types.ints.positive; default = null; - description = '' + description = lib.mdDoc '' Sets the bucket size for the server names hash tables. Default value depends on the processor’s cache line size. ''; @@ -686,7 +686,7 @@ in serverNamesHashMaxSize = mkOption { type = types.nullOr types.ints.positive; default = null; - description = '' + description = lib.mdDoc '' Sets the maximum size of the server names hash tables. ''; }; @@ -698,13 +698,13 @@ in type = types.listOf types.str; default = []; example = literalExpression ''[ "[::1]" "127.0.0.1:5353" ]''; - description = "List of resolvers to use"; + description = lib.mdDoc "List of resolvers to use"; }; valid = mkOption { type = types.str; default = ""; example = "30s"; - description = '' + description = lib.mdDoc '' By default, nginx caches answers using the TTL value of a response. An optional valid parameter allows overriding it ''; @@ -712,7 +712,7 @@ in ipv6 = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' By default, nginx will look up both IPv4 and IPv6 addresses while resolving. If looking up of IPv6 addresses is not desired, the ipv6=off parameter can be specified. @@ -720,7 +720,7 @@ in }; }; }; - description = '' + description = lib.mdDoc '' Configures name servers used to resolve names of upstream servers into addresses ''; default = {}; @@ -735,14 +735,14 @@ in backup = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Marks the server as a backup server. It will be passed requests when the primary servers are unavailable. ''; }; }; }); - description = '' + description = lib.mdDoc '' Defines the address and other parameters of the upstream servers. ''; default = {}; @@ -751,13 +751,13 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' These lines go to the end of the upstream verbatim. ''; }; }; }); - description = '' + description = lib.mdDoc '' Defines a group of servers to use as proxy target. ''; default = {}; @@ -789,7 +789,7 @@ in }; }; ''; - description = "Declarative vhost config"; + description = lib.mdDoc "Declarative vhost config"; }; }; }; diff --git a/nixos/modules/services/web-servers/nginx/location-options.nix b/nixos/modules/services/web-servers/nginx/location-options.nix index 49dd8893015..dc68194f752 100644 --- a/nixos/modules/services/web-servers/nginx/location-options.nix +++ b/nixos/modules/services/web-servers/nginx/location-options.nix @@ -17,7 +17,7 @@ with lib; user = "password"; }; ''; - description = '' + description = lib.mdDoc '' Basic Auth protection for a vhost. WARNING: This is implemented to store the password in plain text in the @@ -28,9 +28,9 @@ with lib; basicAuthFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Basic Auth password file for a vhost. - Can be created via: <command>htpasswd -c <filename> <username></command>. + Can be created via: {command}`htpasswd -c <filename> <username>`. WARNING: The generate file contains the users' passwords in a non-cryptographically-securely hashed way. @@ -41,7 +41,7 @@ with lib; type = types.nullOr types.str; default = null; example = "http://www.example.org/"; - description = '' + description = lib.mdDoc '' Adds proxy_pass directive and sets recommended proxy headers if recommendedProxySettings is enabled. ''; @@ -51,7 +51,7 @@ with lib; type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to support proxying websocket connections with HTTP/1.1. ''; }; @@ -60,7 +60,7 @@ with lib; type = types.nullOr types.str; default = null; example = "index.php index.html"; - description = '' + description = lib.mdDoc '' Adds index directive. ''; }; @@ -69,7 +69,7 @@ with lib; type = types.nullOr types.str; default = null; example = "$uri =404"; - description = '' + description = lib.mdDoc '' Adds try_files directive. ''; }; @@ -78,7 +78,7 @@ with lib; type = types.nullOr types.path; default = null; example = "/your/root/directory"; - description = '' + description = lib.mdDoc '' Root directory for requests. ''; }; @@ -87,7 +87,7 @@ with lib; type = types.nullOr types.path; default = null; example = "/your/alias/directory"; - description = '' + description = lib.mdDoc '' Alias directory for requests. ''; }; @@ -96,7 +96,7 @@ with lib; type = types.nullOr types.str; default = null; example = "301 http://example.com$request_uri"; - description = '' + description = lib.mdDoc '' Adds a return directive, for e.g. redirections. ''; }; @@ -104,7 +104,7 @@ with lib; fastcgiParams = mkOption { type = types.attrsOf (types.either types.str types.path); default = {}; - description = '' + description = lib.mdDoc '' FastCGI parameters to override. Unlike in the Nginx configuration file, overriding only some default parameters won't unset the default values for other parameters. @@ -114,7 +114,7 @@ with lib; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' These lines go to the end of the location verbatim. ''; }; @@ -133,7 +133,7 @@ with lib; type = types.bool; default = config.services.nginx.recommendedProxySettings; defaultText = literalExpression "config.services.nginx.recommendedProxySettings"; - description = '' + description = lib.mdDoc '' Enable recommended proxy settings. ''; }; diff --git a/nixos/modules/services/web-servers/nginx/vhost-options.nix b/nixos/modules/services/web-servers/nginx/vhost-options.nix index 61eef9f7ac9..a749f8bc20f 100644 --- a/nixos/modules/services/web-servers/nginx/vhost-options.nix +++ b/nixos/modules/services/web-servers/nginx/vhost-options.nix @@ -11,7 +11,7 @@ with lib; serverName = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Name of this virtual host. Defaults to attribute name in virtualHosts. ''; example = "example.org"; @@ -21,43 +21,43 @@ with lib; type = types.listOf types.str; default = []; example = [ "www.example.org" "example.org" ]; - description = '' + description = lib.mdDoc '' Additional names of virtual hosts served by this virtual host configuration. ''; }; listen = mkOption { type = with types; listOf (submodule { options = { - addr = mkOption { type = str; description = "IP address."; }; - port = mkOption { type = int; description = "Port number."; default = 80; }; - ssl = mkOption { type = bool; description = "Enable SSL."; default = false; }; - extraParameters = mkOption { type = listOf str; description = "Extra parameters of this listen directive."; default = []; example = [ "backlog=1024" "deferred" ]; }; + addr = mkOption { type = str; description = lib.mdDoc "IP address."; }; + port = mkOption { type = int; description = lib.mdDoc "Port number."; default = 80; }; + ssl = mkOption { type = bool; description = lib.mdDoc "Enable SSL."; default = false; }; + extraParameters = mkOption { type = listOf str; description = lib.mdDoc "Extra parameters of this listen directive."; default = []; example = [ "backlog=1024" "deferred" ]; }; }; }); default = []; example = [ { addr = "195.154.1.1"; port = 443; ssl = true; } { addr = "192.154.1.1"; port = 80; } ]; - description = '' + description = lib.mdDoc '' Listen addresses and ports for this virtual host. IPv6 addresses must be enclosed in square brackets. - Note: this option overrides <literal>addSSL</literal> - and <literal>onlySSL</literal>. + Note: this option overrides `addSSL` + and `onlySSL`. If you only want to set the addresses manually and not - the ports, take a look at <literal>listenAddresses</literal> + the ports, take a look at `listenAddresses` ''; }; listenAddresses = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' Listen addresses for this virtual host. - Compared to <literal>listen</literal> this only sets the addreses + Compared to `listen` this only sets the addreses and the ports are choosen automatically. - Note: This option overrides <literal>enableIPv6</literal> + Note: This option overrides `enableIPv6` ''; default = []; example = [ "127.0.0.1" "[::1]" ]; @@ -66,9 +66,9 @@ with lib; enableACME = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to ask Let's Encrypt to sign a certificate for this vhost. - Alternately, you can use an existing certificate through <option>useACMEHost</option>. + Alternately, you can use an existing certificate through {option}`useACMEHost`. ''; }; @@ -87,7 +87,7 @@ with lib; acmeRoot = mkOption { type = types.nullOr types.str; default = "/var/lib/acme/acme-challenge"; - description = '' + description = lib.mdDoc '' Directory for the acme challenge which is PUBLIC, don't put certs or keys in here. Set to null to inherit from config.security.acme. ''; @@ -96,7 +96,7 @@ with lib; acmeFallbackHost = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Host which to proxy requests to if acme challenge is not found. Useful if you want multiple hosts to be able to verify the same domain name. ''; @@ -105,9 +105,9 @@ with lib; addSSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable HTTPS in addition to plain HTTP. This will set defaults for - <literal>listen</literal> to listen on all interfaces on the respective default + `listen` to listen on all interfaces on the respective default ports (80, 443). ''; }; @@ -115,9 +115,9 @@ with lib; onlySSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable HTTPS and reject plain HTTP connections. This will set - defaults for <literal>listen</literal> to listen on all interfaces on port 443. + defaults for `listen` to listen on all interfaces on port 443. ''; }; @@ -130,10 +130,10 @@ with lib; forceSSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to add a separate nginx server block that permanently redirects (301) all plain HTTP traffic to HTTPS. This will set defaults for - <literal>listen</literal> to listen on all interfaces on the respective default + `listen` to listen on all interfaces on the respective default ports (80, 443), where the non-SSL listens are used for the redirect vhosts. ''; }; @@ -141,11 +141,11 @@ with lib; rejectSSL = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to listen for and reject all HTTPS connections to this vhost. Useful in - <link linkend="opt-services.nginx.virtualHosts._name_.default">default</link> + [default](#opt-services.nginx.virtualHosts._name_.default) server blocks to avoid serving the certificate for another vhost. Uses the - <literal>ssl_reject_handshake</literal> directive available in nginx versions + `ssl_reject_handshake` directive available in nginx versions 1.19.4 and above. ''; }; @@ -153,7 +153,7 @@ with lib; kTLS = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable kTLS support. Implementing TLS in the kernel (kTLS) improves performance by significantly reducing the need for copying operations between user space and the kernel. @@ -164,26 +164,26 @@ with lib; sslCertificate = mkOption { type = types.path; example = "/var/host.cert"; - description = "Path to server SSL certificate."; + description = lib.mdDoc "Path to server SSL certificate."; }; sslCertificateKey = mkOption { type = types.path; example = "/var/host.key"; - description = "Path to server SSL certificate key."; + description = lib.mdDoc "Path to server SSL certificate key."; }; sslTrustedCertificate = mkOption { type = types.nullOr types.path; default = null; example = literalExpression ''"''${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"''; - description = "Path to root SSL certificate for stapling and client certificates."; + description = lib.mdDoc "Path to root SSL certificate for stapling and client certificates."; }; http2 = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable HTTP 2. Note that (as of writing) due to nginx's implementation, to disable HTTP 2 you have to disable it on all vhosts that use a given @@ -210,7 +210,7 @@ with lib; reuseport = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Create an individual listening socket . It is required to specify only once on one of the hosts. ''; @@ -220,7 +220,7 @@ with lib; type = types.nullOr types.path; default = null; example = "/data/webserver/docs"; - description = '' + description = lib.mdDoc '' The path of the web root directory. ''; }; @@ -228,7 +228,7 @@ with lib; default = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Makes this vhost the default. ''; }; @@ -236,7 +236,7 @@ with lib; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' These lines go to the end of the vhost verbatim. ''; }; @@ -245,7 +245,7 @@ with lib; type = types.nullOr types.str; default = null; example = "newserver.example.org"; - description = '' + description = lib.mdDoc '' If set, all requests for this host are redirected permanently to the given hostname. ''; @@ -259,7 +259,7 @@ with lib; user = "password"; }; ''; - description = '' + description = lib.mdDoc '' Basic Auth protection for a vhost. WARNING: This is implemented to store the password in plain text in the @@ -270,9 +270,9 @@ with lib; basicAuthFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Basic Auth password file for a vhost. - Can be created via: <command>htpasswd -c <filename> <username></command>. + Can be created via: {command}`htpasswd -c <filename> <username>`. WARNING: The generate file contains the users' passwords in a non-cryptographically-securely hashed way. @@ -291,7 +291,7 @@ with lib; }; }; ''; - description = "Declarative location config"; + description = lib.mdDoc "Declarative location config"; }; }; } diff --git a/nixos/modules/services/x11/desktop-managers/default.nix b/nixos/modules/services/x11/desktop-managers/default.nix index ffdf7e9a86e..a0fc3e4b5ab 100644 --- a/nixos/modules/services/x11/desktop-managers/default.nix +++ b/nixos/modules/services/x11/desktop-managers/default.nix @@ -33,25 +33,25 @@ in type = types.enum [ "center" "fill" "max" "scale" "tile" ]; default = "scale"; example = "fill"; - description = '' - The file <filename>~/.background-image</filename> is used as a background image. + description = lib.mdDoc '' + The file {file}`~/.background-image` is used as a background image. This option specifies the placement of this image onto your desktop. Possible values: - <literal>center</literal>: Center the image on the background. If it is too small, it will be surrounded by a black border. - <literal>fill</literal>: Like <literal>scale</literal>, but preserves aspect ratio by zooming the image until it fits. Either a horizontal or a vertical part of the image will be cut off. - <literal>max</literal>: Like <literal>fill</literal>, but scale the image to the maximum size that fits the screen with black borders on one side. - <literal>scale</literal>: Fit the file into the background without repeating it, cutting off stuff or using borders. But the aspect ratio is not preserved either. - <literal>tile</literal>: Tile (repeat) the image in case it is too small for the screen. + `center`: Center the image on the background. If it is too small, it will be surrounded by a black border. + `fill`: Like `scale`, but preserves aspect ratio by zooming the image until it fits. Either a horizontal or a vertical part of the image will be cut off. + `max`: Like `fill`, but scale the image to the maximum size that fits the screen with black borders on one side. + `scale`: Fit the file into the background without repeating it, cutting off stuff or using borders. But the aspect ratio is not preserved either. + `tile`: Tile (repeat) the image in case it is too small for the screen. ''; }; combineScreens = mkOption { type = types.bool; default = false; - description = '' - When set to <literal>true</literal> the wallpaper will stretch across all screens. - When set to <literal>false</literal> the wallpaper is duplicated to all screens. + description = lib.mdDoc '' + When set to `true` the wallpaper will stretch across all screens. + When set to `false` the wallpaper is duplicated to all screens. ''; }; }; diff --git a/nixos/modules/services/x11/display-managers/lightdm.nix b/nixos/modules/services/x11/display-managers/lightdm.nix index 302c8fe0d91..2d1ae0ed0a3 100644 --- a/nixos/modules/services/x11/display-managers/lightdm.nix +++ b/nixos/modules/services/x11/display-managers/lightdm.nix @@ -105,7 +105,7 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable lightdm as the display manager. ''; }; @@ -114,14 +114,14 @@ in enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' If set to false, run lightdm in greeterless mode. This only works if autologin is enabled and autoLogin.timeout is zero. ''; }; package = mkOption { type = types.package; - description = '' + description = lib.mdDoc '' The LightDM greeter to login via. The package should be a directory containing a .desktop file matching the name in the 'name' option. ''; @@ -129,7 +129,7 @@ in }; name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The name of a .desktop file in the directory specified in the 'package' option. ''; @@ -142,14 +142,14 @@ in example = '' user-authority-in-system-dir = true ''; - description = "Extra lines to append to LightDM section."; + description = lib.mdDoc "Extra lines to append to LightDM section."; }; background = mkOption { type = types.either types.path (types.strMatching "^#[0-9]\{6\}$"); # Manual cannot depend on packages, we are actually setting the default in config below. defaultText = literalExpression "pkgs.nixos-artwork.wallpapers.simple-dark-gray-bottom.gnomeFilePath"; - description = '' + description = lib.mdDoc '' The background image or color to use. ''; }; @@ -160,14 +160,14 @@ in example = '' greeter-show-manual-login=true ''; - description = "Extra lines to append to SeatDefaults section."; + description = lib.mdDoc "Extra lines to append to SeatDefaults section."; }; # Configuration for automatic login specific to LightDM autoLogin.timeout = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Show the greeter for this many seconds before automatic login occurs. ''; }; diff --git a/nixos/modules/services/x11/xserver.nix b/nixos/modules/services/x11/xserver.nix index efe1a13fd5d..dc48f3ac030 100644 --- a/nixos/modules/services/x11/xserver.nix +++ b/nixos/modules/services/x11/xserver.nix @@ -37,16 +37,16 @@ let output = mkOption { type = types.str; example = "DVI-0"; - description = '' + description = lib.mdDoc '' The output name of the monitor, as shown by - <citerefentry><refentrytitle>xrandr</refentrytitle><manvolnum>1</manvolnum></citerefentry> invoked without arguments. + {manpage}`xrandr(1)` invoked without arguments. ''; }; primary = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether this head is treated as the primary monitor, ''; }; @@ -58,10 +58,10 @@ let DisplaySize 408 306 Option "DPMS" "false" ''; - description = '' - Extra lines to append to the <literal>Monitor</literal> section + description = lib.mdDoc '' + Extra lines to append to the `Monitor` section verbatim. Available options are documented in the MONITOR section in - <citerefentry><refentrytitle>xorg.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`xorg.conf(5)`. ''; }; }; @@ -165,7 +165,7 @@ in enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable the X server. ''; }; @@ -173,7 +173,7 @@ in autorun = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to start the X server automatically. ''; }; @@ -182,22 +182,22 @@ in default = []; example = literalExpression "[ pkgs.xterm ]"; type = types.listOf types.package; - description = "Which X11 packages to exclude from the default environment"; + description = lib.mdDoc "Which X11 packages to exclude from the default environment"; }; exportConfiguration = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to symlink the X server configuration under - <filename>/etc/X11/xorg.conf</filename>. + {file}`/etc/X11/xorg.conf`. ''; }; enableTCP = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to allow the X server to accept TCP connections. ''; }; @@ -205,7 +205,7 @@ in autoRepeatDelay = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts). ''; }; @@ -213,7 +213,7 @@ in autoRepeatInterval = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes). ''; }; @@ -231,21 +231,21 @@ in ''' ] ''; - description = "Content of additional InputClass sections of the X server configuration file."; + description = lib.mdDoc "Content of additional InputClass sections of the X server configuration file."; }; modules = mkOption { type = types.listOf types.path; default = []; example = literalExpression "[ pkgs.xf86_input_wacom ]"; - description = "Packages to be added to the module search path of the X server."; + description = lib.mdDoc "Packages to be added to the module search path of the X server."; }; resolutions = mkOption { type = types.listOf types.attrs; default = []; example = [ { x = 1600; y = 1200; } { x = 1024; y = 786; } ]; - description = '' + description = lib.mdDoc '' The screen resolutions for the X server. The first element is the default resolution. If this list is empty, the X server will automatically configure the resolution. @@ -266,7 +266,7 @@ in path = [ "xorg" n ]; title = removePrefix "xf86video" n; }) pkgs.xorg); - description = '' + description = lib.mdDoc '' The names of the video drivers the configuration supports. They will be tried in order until one that supports your card is found. @@ -282,10 +282,10 @@ in type = types.nullOr types.str; default = null; example = "i810"; - description = '' + description = lib.mdDoc '' The name of the video driver for your graphics card. This option is obsolete; please set the - <option>services.xserver.videoDrivers</option> instead. + {option}`services.xserver.videoDrivers` instead. ''; }; @@ -301,17 +301,17 @@ in dpi = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Force global DPI resolution to use for X server. It's recommended to use this only when DPI is detected incorrectly; also consider using - <literal>Monitor</literal> section in configuration file instead. + `Monitor` section in configuration file instead. ''; }; updateDbusEnvironment = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to update the DBus activation environment after launching the desktop manager. ''; @@ -320,7 +320,7 @@ in layout = mkOption { type = types.str; default = "us"; - description = '' + description = lib.mdDoc '' Keyboard layout, or multiple keyboard layouts separated by commas. ''; }; @@ -329,7 +329,7 @@ in type = types.str; default = "pc104"; example = "presario"; - description = '' + description = lib.mdDoc '' Keyboard model. ''; }; @@ -338,7 +338,7 @@ in type = types.commas; default = "terminate:ctrl_alt_bksp"; example = "grp:caps_toggle,grp_led:scroll"; - description = '' + description = lib.mdDoc '' X keyboard options; layout switching goes here. ''; }; @@ -347,7 +347,7 @@ in type = types.str; default = ""; example = "colemak"; - description = '' + description = lib.mdDoc '' X keyboard variant. ''; }; @@ -356,22 +356,22 @@ in type = types.path; default = "${pkgs.xkeyboard_config}/etc/X11/xkb"; defaultText = literalExpression ''"''${pkgs.xkeyboard_config}/etc/X11/xkb"''; - description = '' + description = lib.mdDoc '' Path used for -xkbdir xserver parameter. ''; }; config = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' The contents of the configuration file of the X server - (<filename>xorg.conf</filename>). + ({file}`xorg.conf`). This option is set by multiple modules, and the configs are concatenated together. In Xorg configs the last config entries take precedence, - so you may want to use <literal>lib.mkAfter</literal> on this option + so you may want to use `lib.mkAfter` on this option to override NixOS's defaults. ''; }; @@ -380,14 +380,14 @@ in type = types.lines; default = ""; example = ''FontPath "/path/to/my/fonts"''; - description = "Contents of the first <literal>Files</literal> section of the X server configuration file."; + description = lib.mdDoc "Contents of the first `Files` section of the X server configuration file."; }; deviceSection = mkOption { type = types.lines; default = ""; example = "VideoRAM 131072"; - description = "Contents of the first Device section of the X server configuration file."; + description = lib.mdDoc "Contents of the first Device section of the X server configuration file."; }; screenSection = mkOption { @@ -396,20 +396,20 @@ in example = '' Option "RandRRotation" "on" ''; - description = "Contents of the first Screen section of the X server configuration file."; + description = lib.mdDoc "Contents of the first Screen section of the X server configuration file."; }; monitorSection = mkOption { type = types.lines; default = ""; example = "HorizSync 28-49"; - description = "Contents of the first Monitor section of the X server configuration file."; + description = lib.mdDoc "Contents of the first Monitor section of the X server configuration file."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = "Additional contents (sections) included in the X server configuration file"; + description = lib.mdDoc "Additional contents (sections) included in the X server configuration file"; }; xrandrHeads = mkOption { @@ -463,7 +463,7 @@ in Option "SuspendTime" "0" Option "OffTime" "0" ''; - description = "Contents of the ServerFlags section of the X server configuration file."; + description = lib.mdDoc "Contents of the ServerFlags section of the X server configuration file."; }; moduleSection = mkOption { @@ -474,7 +474,7 @@ in SubSection "extmod" EndSubsection ''; - description = "Contents of the Module section of the X server configuration file."; + description = lib.mdDoc "Contents of the Module section of the X server configuration file."; }; serverLayoutSection = mkOption { @@ -484,28 +484,28 @@ in '' Option "AIGLX" "true" ''; - description = "Contents of the ServerLayout section of the X server configuration file."; + description = lib.mdDoc "Contents of the ServerLayout section of the X server configuration file."; }; extraDisplaySettings = mkOption { type = types.lines; default = ""; example = "Virtual 2048 2048"; - description = "Lines to be added to every Display subsection of the Screen section."; + description = lib.mdDoc "Lines to be added to every Display subsection of the Screen section."; }; defaultDepth = mkOption { type = types.int; default = 0; example = 8; - description = "Default colour depth."; + description = lib.mdDoc "Default colour depth."; }; fontPath = mkOption { type = types.nullOr types.str; default = null; example = "unix/:7100"; - description = '' + description = lib.mdDoc '' Set the X server FontPath. Defaults to null, which means the compiled in defaults will be used. See man xorg.conf for details. @@ -515,20 +515,20 @@ in tty = mkOption { type = types.nullOr types.int; default = 7; - description = "Virtual console for the X server."; + description = lib.mdDoc "Virtual console for the X server."; }; display = mkOption { type = types.nullOr types.int; default = 0; - description = "Display number for the X server."; + description = lib.mdDoc "Display number for the X server."; }; virtualScreen = mkOption { type = types.nullOr types.attrs; default = null; example = { x = 2048; y = 2048; }; - description = '' + description = lib.mdDoc '' Virtual screen size for Xrandr. ''; }; @@ -537,12 +537,12 @@ in type = types.nullOr types.str; default = "/dev/null"; example = "/var/log/Xorg.0.log"; - description = '' + description = lib.mdDoc '' Controls the file Xorg logs to. - The default of <literal>/dev/null</literal> is set so that systemd services (like <literal>displayManagers</literal>) only log to the journal and don't create their own log files. + The default of `/dev/null` is set so that systemd services (like `displayManagers`) only log to the journal and don't create their own log files. - Setting this to <literal>null</literal> will not pass the <literal>-logfile</literal> argument to Xorg which allows it to log to its default logfile locations instead (see <literal>man Xorg</literal>). You probably only want this behaviour when running Xorg manually (e.g. via <literal>startx</literal>). + Setting this to `null` will not pass the `-logfile` argument to Xorg which allows it to log to its default logfile locations instead (see `man Xorg`). You probably only want this behaviour when running Xorg manually (e.g. via `startx`). ''; }; @@ -550,7 +550,7 @@ in type = types.nullOr types.int; default = 3; example = 7; - description = '' + description = lib.mdDoc '' Controls verbosity of X logging. ''; }; @@ -558,7 +558,7 @@ in useGlamor = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to use the Glamor module for 2D acceleration, if possible. ''; @@ -567,7 +567,7 @@ in enableCtrlAltBackspace = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable the DontZap option, which binds Ctrl+Alt+Backspace to forcefully kill X. This can lead to data loss and is disabled by default. @@ -577,7 +577,7 @@ in terminateOnReset = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to terminate X upon server reset. ''; }; diff --git a/nixos/modules/system/activation/top-level.nix b/nixos/modules/system/activation/top-level.nix index 87ff1d97d8f..56b072d2b69 100644 --- a/nixos/modules/system/activation/top-level.nix +++ b/nixos/modules/system/activation/top-level.nix @@ -185,12 +185,12 @@ in options.inheritParentConfig = mkOption { type = types.bool; default = true; - description = "Include the entire system's configuration. Set to false to make a completely differently configured system."; + description = lib.mdDoc "Include the entire system's configuration. Set to false to make a completely differently configured system."; }; options.configuration = mkOption { default = {}; - description = '' + description = lib.mdDoc '' Arbitrary NixOS configuration. Anything you can add to a normal NixOS configuration, you can add @@ -255,7 +255,7 @@ in toplevel = mkOption { type = types.package; readOnly = true; - description = '' + description = lib.mdDoc '' This option contains the store path that typically represents a NixOS system. You can read this path in a custom deployment tool for example. @@ -267,11 +267,11 @@ in system.copySystemConfiguration = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If enabled, copies the NixOS configuration file - (usually <filename>/etc/nixos/configuration.nix</filename>) + (usually {file}`/etc/nixos/configuration.nix`) and links it from the resulting system - (getting to <filename>/run/current-system/configuration.nix</filename>). + (getting to {file}`/run/current-system/configuration.nix`). Note that only this single file is copied, even if it imports others. ''; }; @@ -288,7 +288,7 @@ in system.extraDependencies = mkOption { type = types.listOf types.package; default = []; - description = '' + description = lib.mdDoc '' A list of packages that should be included in the system closure but not otherwise made available to users. This is primarily used by the installation tests. @@ -302,12 +302,12 @@ in { ... }: { options.original = mkOption { type = types.package; - description = "The original package to override."; + description = lib.mdDoc "The original package to override."; }; options.replacement = mkOption { type = types.package; - description = "The replacement package."; + description = lib.mdDoc "The replacement package."; }; }) ); @@ -315,7 +315,7 @@ in oldDependency = original; newDependency = replacement; }); - description = '' + description = lib.mdDoc '' List of packages to override without doing a full rebuild. The original derivation and replacement derivation must have the same name length, and ideally should have close-to-identical directory layout. @@ -333,11 +333,11 @@ in then "unnamed" else config.networking.hostName; ''; - description = '' - The name of the system used in the <option>system.build.toplevel</option> derivation. + description = lib.mdDoc '' + The name of the system used in the {option}`system.build.toplevel` derivation. That derivation has the following name: - <literal>"nixos-system-''${config.system.name}-''${config.system.nixos.label}"</literal> + `"nixos-system-''${config.system.name}-''${config.system.nixos.label}"` ''; }; diff --git a/nixos/modules/system/boot/loader/generic-extlinux-compatible/default.nix b/nixos/modules/system/boot/loader/generic-extlinux-compatible/default.nix index 545b594674f..5ef3c5cd52a 100644 --- a/nixos/modules/system/boot/loader/generic-extlinux-compatible/default.nix +++ b/nixos/modules/system/boot/loader/generic-extlinux-compatible/default.nix @@ -20,12 +20,12 @@ in enable = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to generate an extlinux-compatible configuration file - under <literal>/boot/extlinux.conf</literal>. For instance, + under `/boot/extlinux.conf`. For instance, U-Boot's generic distro boot support uses this file format. - See <link xlink:href="http://git.denx.de/?p=u-boot.git;a=blob;f=doc/README.distro;hb=refs/heads/master">U-boot's documentation</link> + See [U-boot's documentation](http://git.denx.de/?p=u-boot.git;a=blob;f=doc/README.distro;hb=refs/heads/master) for more information. ''; }; @@ -33,7 +33,7 @@ in useGenerationDeviceTree = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to generate Device Tree-related directives in the extlinux configuration. @@ -49,7 +49,7 @@ in default = 20; example = 10; type = types.int; - description = '' + description = lib.mdDoc '' Maximum number of configurations in the boot menu. ''; }; @@ -57,9 +57,9 @@ in populateCmd = mkOption { type = types.str; readOnly = true; - description = '' + description = lib.mdDoc '' Contains the builder command used to populate an image, - honoring all options except the <literal>-c <path-to-default-configuration></literal> + honoring all options except the `-c <path-to-default-configuration>` argument. Useful to have for sdImage.populateRootCommands ''; diff --git a/nixos/modules/system/boot/modprobe.nix b/nixos/modules/system/boot/modprobe.nix index 89d31517b0d..c8ab3b0d8e4 100644 --- a/nixos/modules/system/boot/modprobe.nix +++ b/nixos/modules/system/boot/modprobe.nix @@ -24,11 +24,11 @@ with lib; '' options parport_pc io=0x378 irq=7 dma=1 ''; - description = '' + description = lib.mdDoc '' Any additional configuration to be appended to the generated - <filename>modprobe.conf</filename>. This is typically used to + {file}`modprobe.conf`. This is typically used to specify module options. See - <citerefentry><refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + {manpage}`modprobe.d(5)` for details. ''; type = types.lines; }; diff --git a/nixos/modules/system/boot/networkd.nix b/nixos/modules/system/boot/networkd.nix index c6d92b1d252..337d238f910 100644 --- a/nixos/modules/system/boot/networkd.nix +++ b/nixos/modules/system/boot/networkd.nix @@ -916,10 +916,10 @@ let default = {}; example = { SpeedMeter = true; ManageForeignRoutingPolicyRules = false; }; type = types.addCheck (types.attrsOf unitOption) check.global.sectionNetwork; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Network]</literal> section of the networkd config. - See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Network]` section of the networkd config. + See {manpage}`networkd.conf(5)` for details. ''; }; @@ -927,10 +927,10 @@ let default = {}; example = { DUIDType = "vendor"; }; type = types.addCheck (types.attrsOf unitOption) check.global.sectionDHCPv4; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPv4]</literal> section of the networkd config. - See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPv4]` section of the networkd config. + See {manpage}`networkd.conf(5)` for details. ''; }; @@ -938,10 +938,10 @@ let default = {}; example = { DUIDType = "vendor"; }; type = types.addCheck (types.attrsOf unitOption) check.global.sectionDHCPv6; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPv6]</literal> section of the networkd config. - See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPv6]` section of the networkd config. + See {manpage}`networkd.conf(5)` for details. ''; }; }; @@ -960,10 +960,10 @@ let default = {}; example = { MACAddress = "00:ff:ee:aa:cc:dd"; }; type = types.addCheck (types.attrsOf unitOption) check.link.sectionLink; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Link]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Link]` section of the unit. See + {manpage}`systemd.link(5)` for details. ''; }; @@ -974,10 +974,10 @@ let wireguardPeerConfig = mkOption { default = {}; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionWireGuardPeer; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[WireGuardPeer]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[WireGuardPeer]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; }; @@ -988,10 +988,10 @@ let netdevConfig = mkOption { example = { Name = "mybridge"; Kind = "bridge"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionNetdev; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Netdev]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Netdev]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -999,10 +999,10 @@ let default = {}; example = { Id = 4; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionVLAN; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[VLAN]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[VLAN]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1010,20 +1010,20 @@ let default = {}; example = { Mode = "private"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionMACVLAN; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[MACVLAN]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[MACVLAN]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; vxlanConfig = mkOption { default = {}; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionVXLAN; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[VXLAN]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[VXLAN]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1031,10 +1031,10 @@ let default = {}; example = { Remote = "192.168.1.1"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionTunnel; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Tunnel]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Tunnel]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1042,10 +1042,10 @@ let default = { }; example = { Port = 9001; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionFooOverUDP; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[FooOverUDP]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[FooOverUDP]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1053,10 +1053,10 @@ let default = {}; example = { Name = "veth2"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionPeer; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Peer]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Peer]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1064,10 +1064,10 @@ let default = {}; example = { User = "openvpn"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionTun; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Tun]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Tun]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1075,10 +1075,10 @@ let default = {}; example = { User = "openvpn"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionTap; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Tap]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Tap]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1090,12 +1090,12 @@ let FirewallMark = 42; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionWireGuard; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[WireGuard]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. - Use <literal>PrivateKeyFile</literal> instead of - <literal>PrivateKey</literal>: the nix store is + `[WireGuard]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. + Use `PrivateKeyFile` instead of + `PrivateKey`: the nix store is world-readable. ''; }; @@ -1110,12 +1110,12 @@ let PersistentKeepalive = 15; };}]; type = with types; listOf (submodule wireguardPeerOptions); - description = '' + description = lib.mdDoc '' Each item in this array specifies an option in the - <literal>[WireGuardPeer]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. - Use <literal>PresharedKeyFile</literal> instead of - <literal>PresharedKey</literal>: the nix store is + `[WireGuardPeer]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. + Use `PresharedKeyFile` instead of + `PresharedKey`: the nix store is world-readable. ''; }; @@ -1124,10 +1124,10 @@ let default = {}; example = { Mode = "802.3ad"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionBond; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Bond]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Bond]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1135,10 +1135,10 @@ let default = {}; example = { InterfaceId = 1; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionXfrm; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Xfrm]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Xfrm]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1146,12 +1146,12 @@ let default = {}; example = { Table = 2342; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionVRF; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[VRF]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[VRF]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. A detailed explanation about how VRFs work can be found in the - <link xlink:href="https://www.kernel.org/doc/Documentation/networking/vrf.txt">kernel docs</link>. + [kernel docs](https://www.kernel.org/doc/Documentation/networking/vrf.txt). ''; }; @@ -1162,10 +1162,10 @@ let RoutingAlgorithm = "batman-v"; }; type = types.addCheck (types.attrsOf unitOption) check.netdev.sectionBatmanAdvanced; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[BatmanAdvanced]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[BatmanAdvanced]` section of the unit. See + {manpage}`systemd.netdev(5)` for details. ''; }; @@ -1176,10 +1176,10 @@ let addressConfig = mkOption { example = { Address = "192.168.0.100/24"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionAddress; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Address]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Address]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; }; @@ -1191,10 +1191,10 @@ let default = { }; example = { Table = 10; IncomingInterface = "eth1"; Family = "both"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionRoutingPolicyRule; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[RoutingPolicyRule]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[RoutingPolicyRule]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; }; @@ -1206,10 +1206,10 @@ let default = {}; example = { Gateway = "192.168.0.1"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionRoute; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Route]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Route]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; }; @@ -1221,10 +1221,10 @@ let default = {}; example = { Prefix = "fd00::/64"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionIPv6Prefix; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[IPv6Prefix]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[IPv6Prefix]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; }; @@ -1236,13 +1236,13 @@ let default = {}; example = { MACAddress = "65:43:4a:5b:d8:5f"; Address = "192.168.1.42"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPServerStaticLease; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPServerStaticLease]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPServerStaticLease]` section of the unit. See + {manpage}`systemd.network(5)` for details. Make sure to configure the corresponding client interface to use - <literal>ClientIdentifier=mac</literal>. + `ClientIdentifier=mac`. ''; }; }; @@ -1254,10 +1254,10 @@ let default = {}; example = { Unmanaged = true; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionLink; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Link]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Link]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1265,10 +1265,10 @@ let default = {}; example = { Description = "My Network"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionNetwork; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Network]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Network]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1283,10 +1283,10 @@ let default = {}; example = { UseDNS = true; UseRoutes = true; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPv4; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPv4]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPv4]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1294,10 +1294,10 @@ let default = {}; example = { UseDNS = true; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPv6; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPv6]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPv6]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1305,10 +1305,10 @@ let default = {}; example = { SubnetId = "auto"; Announce = true; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPv6PrefixDelegation; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPv6PrefixDelegation]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPv6PrefixDelegation]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1316,10 +1316,10 @@ let default = {}; example = { UseDNS = true; DHCPv6Client = "always"; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionIPv6AcceptRA; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[IPv6AcceptRA]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[IPv6AcceptRA]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1327,10 +1327,10 @@ let default = {}; example = { PoolOffset = 50; EmitDNS = false; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionDHCPServer; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[DHCPServer]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[DHCPServer]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1345,10 +1345,10 @@ let default = {}; example = { EmitDNS = true; Managed = true; OtherInformation = true; }; type = types.addCheck (types.attrsOf unitOption) check.network.sectionIPv6SendRA; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[IPv6SendRA]</literal> section of the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[IPv6SendRA]` section of the unit. See + {manpage}`systemd.network(5)` for details. ''; }; @@ -1356,9 +1356,9 @@ let default = []; example = [ { dhcpServerStaticLeaseConfig = { MACAddress = "65:43:4a:5b:d8:5f"; Address = "192.168.1.42"; }; } ]; type = with types; listOf (submodule dhcpServerStaticLeaseOptions); - description = '' + description = lib.mdDoc '' A list of DHCPServerStaticLease sections to be added to the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + {manpage}`systemd.network(5)` for details. ''; }; @@ -1366,9 +1366,9 @@ let default = []; example = [ { ipv6PrefixConfig = { AddressAutoconfiguration = true; OnLink = true; }; } ]; type = with types; listOf (submodule ipv6PrefixOptions); - description = '' + description = lib.mdDoc '' A list of ipv6Prefix sections to be added to the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + {manpage}`systemd.network(5)` for details. ''; }; @@ -1399,135 +1399,135 @@ let address = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of addresses to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; gateway = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of gateways to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; dns = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of dns servers to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; ntp = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of ntp servers to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; bridge = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of bridge interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; bond = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of bond interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; vrf = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of vrf interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; vlan = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of vlan interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; macvlan = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of macvlan interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; vxlan = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of vxlan interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; tunnel = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of tunnel interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; xfrm = mkOption { default = [ ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' A list of xfrm interfaces to be added to the network section of the - unit. See <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + unit. See {manpage}`systemd.network(5)` for details. ''; }; addresses = mkOption { default = [ ]; type = with types; listOf (submodule addressOptions); - description = '' + description = lib.mdDoc '' A list of address sections to be added to the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + {manpage}`systemd.network(5)` for details. ''; }; routingPolicyRules = mkOption { default = [ ]; type = with types; listOf (submodule routingPolicyRulesOptions); - description = '' + description = lib.mdDoc '' A list of routing policy rules sections to be added to the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + {manpage}`systemd.network(5)` for details. ''; }; routes = mkOption { default = [ ]; type = with types; listOf (submodule routeOptions); - description = '' + description = lib.mdDoc '' A list of route sections to be added to the unit. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + {manpage}`systemd.network(5)` for details. ''; }; @@ -1552,9 +1552,9 @@ let default = {}; example = { foo = 27; }; type = with types; attrsOf int; - description = '' + description = lib.mdDoc '' Defines route table names as an attrset of name to number. - See <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + See {manpage}`networkd.conf(5)` for details. ''; }; diff --git a/nixos/modules/system/boot/systemd/nspawn.nix b/nixos/modules/system/boot/systemd/nspawn.nix index f6364e5853c..0d06fb3c032 100644 --- a/nixos/modules/system/boot/systemd/nspawn.nix +++ b/nixos/modules/system/boot/systemd/nspawn.nix @@ -50,10 +50,10 @@ let default = {}; example = { Parameters = "/bin/sh"; }; type = types.addCheck (types.attrsOf unitOption) checkExec; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Exec]</literal> section of this unit. See - <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Exec]` section of this unit. See + {manpage}`systemd.nspawn(5)` for details. ''; }; @@ -61,10 +61,10 @@ let default = {}; example = { Bind = [ "/home/alice" ]; }; type = types.addCheck (types.attrsOf unitOption) checkFiles; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Files]</literal> section of this unit. See - <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Files]` section of this unit. See + {manpage}`systemd.nspawn(5)` for details. ''; }; @@ -72,10 +72,10 @@ let default = {}; example = { Private = false; }; type = types.addCheck (types.attrsOf unitOption) checkNetwork; - description = '' + description = lib.mdDoc '' Each attribute in this set specifies an option in the - <literal>[Network]</literal> section of this unit. See - <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. + `[Network]` section of this unit. See + {manpage}`systemd.nspawn(5)` for details. ''; }; }; diff --git a/nixos/modules/tasks/auto-upgrade.nix b/nixos/modules/tasks/auto-upgrade.nix index d2de7ab47b2..bfc5265518d 100644 --- a/nixos/modules/tasks/auto-upgrade.nix +++ b/nixos/modules/tasks/auto-upgrade.nix @@ -77,12 +77,12 @@ in { type = types.str; default = "04:40"; example = "daily"; - description = '' + description = lib.mdDoc '' How often or when upgrade occurs. For most desktop and server systems a sufficient upgrade frequency is once a day. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; @@ -101,11 +101,11 @@ in { default = "0"; type = types.str; example = "45min"; - description = '' + description = lib.mdDoc '' Add a randomized delay before each automatic upgrade. The delay will be chosen between zero and this value. This value must be a time span in the format specified by - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + {manpage}`systemd.time(7)` ''; }; diff --git a/nixos/modules/tasks/filesystems/btrfs.nix b/nixos/modules/tasks/filesystems/btrfs.nix index beda486a115..32bfaba95c2 100644 --- a/nixos/modules/tasks/filesystems/btrfs.nix +++ b/nixos/modules/tasks/filesystems/btrfs.nix @@ -36,12 +36,12 @@ in default = "monthly"; type = types.str; example = "weekly"; - description = '' + description = lib.mdDoc '' Systemd calendar expression for when to scrub btrfs filesystems. The recommended period is a month but could be less - (<citerefentry><refentrytitle>btrfs-scrub</refentrytitle><manvolnum>8</manvolnum></citerefentry>). + ({manpage}`btrfs-scrub(8)`). See - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + {manpage}`systemd.time(7)` for more information on the syntax. ''; }; diff --git a/nixos/modules/tasks/filesystems/zfs.nix b/nixos/modules/tasks/filesystems/zfs.nix index ac088d8dacb..7feb7eeee60 100644 --- a/nixos/modules/tasks/filesystems/zfs.nix +++ b/nixos/modules/tasks/filesystems/zfs.nix @@ -388,12 +388,12 @@ in default = "weekly"; type = types.str; example = "daily"; - description = '' + description = lib.mdDoc '' How often we run trim. For most desktop and server systems a sufficient trimming frequency is once a week. The format is described in - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; }; @@ -405,9 +405,9 @@ in default = "Sun, 02:00"; type = types.str; example = "daily"; - description = '' + description = lib.mdDoc '' Systemd calendar expression when to scrub ZFS pools. See - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + {manpage}`systemd.time(7)`. ''; }; diff --git a/nixos/modules/tasks/network-interfaces.nix b/nixos/modules/tasks/network-interfaces.nix index 658e6f3391c..fabddece376 100644 --- a/nixos/modules/tasks/network-interfaces.nix +++ b/nixos/modules/tasks/network-interfaces.nix @@ -876,9 +876,9 @@ in primary = { port = 9001; local = { address = "192.0.2.1"; dev = "eth0"; }; }; backup = { port = 9002; }; }; - description = '' + description = lib.mdDoc '' This option allows you to configure Foo Over UDP and Generic UDP Encapsulation - endpoints. See <citerefentry><refentrytitle>ip-fou</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details. + endpoints. See {manpage}`ip-fou(8)` for details. ''; type = with types; attrsOf (submodule { options = { @@ -997,9 +997,9 @@ in options = { type = mkOption { type = enum [ "fou" "gue" ]; - description = '' + description = lib.mdDoc '' Selects encapsulation type. See - <citerefentry><refentrytitle>ip-link</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details. + {manpage}`ip-link(8)` for details. ''; }; diff --git a/nixos/modules/virtualisation/azure-agent.nix b/nixos/modules/virtualisation/azure-agent.nix index e2425b44eac..31047c4ddc0 100644 --- a/nixos/modules/virtualisation/azure-agent.nix +++ b/nixos/modules/virtualisation/azure-agent.nix @@ -60,15 +60,15 @@ in options.virtualisation.azure.agent = { enable = mkOption { default = false; - description = "Whether to enable the Windows Azure Linux Agent."; + description = lib.mdDoc "Whether to enable the Windows Azure Linux Agent."; }; verboseLogging = mkOption { default = false; - description = "Whether to enable verbose logging."; + description = lib.mdDoc "Whether to enable verbose logging."; }; mountResourceDisk = mkOption { default = true; - description = "Whether the agent should format (ext4) and mount the resource disk to /mnt/resource."; + description = lib.mdDoc "Whether the agent should format (ext4) and mount the resource disk to /mnt/resource."; }; }; diff --git a/nixos/modules/virtualisation/docker.nix b/nixos/modules/virtualisation/docker.nix index 66e20df8d25..66c94f30088 100644 --- a/nixos/modules/virtualisation/docker.nix +++ b/nixos/modules/virtualisation/docker.nix @@ -142,9 +142,9 @@ in dates = mkOption { default = "weekly"; type = types.str; - description = '' + description = lib.mdDoc '' Specification (in the format described by - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>) of the time at + {manpage}`systemd.time(7)`) of the time at which the prune will occur. ''; }; diff --git a/nixos/modules/virtualisation/lxc.nix b/nixos/modules/virtualisation/lxc.nix index f073f9bdc7c..d7bbc3f8414 100644 --- a/nixos/modules/virtualisation/lxc.nix +++ b/nixos/modules/virtualisation/lxc.nix @@ -31,9 +31,9 @@ in type = types.lines; default = ""; description = - '' + lib.mdDoc '' This is the system-wide LXC config. See - <citerefentry><refentrytitle>lxc.system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + {manpage}`lxc.system.conf(5)`. ''; }; @@ -42,9 +42,9 @@ in type = types.lines; default = ""; description = - '' + lib.mdDoc '' Default config (default.conf) for new containers, i.e. for - network config. See <citerefentry><refentrytitle>lxc.container.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + network config. See {manpage}`lxc.container.conf(5)`. ''; }; diff --git a/nixos/modules/virtualisation/nixos-containers.nix b/nixos/modules/virtualisation/nixos-containers.nix index 8592179bc06..b08c8396ef3 100644 --- a/nixos/modules/virtualisation/nixos-containers.nix +++ b/nixos/modules/virtualisation/nixos-containers.nix @@ -629,10 +629,10 @@ in timeoutStartSec = mkOption { type = types.str; default = "1min"; - description = '' + description = lib.mdDoc '' Time for the container to start. In case of a timeout, the container processes get killed. - See <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + See {manpage}`systemd.time(7)` for more information about the format. ''; }; diff --git a/nixos/modules/virtualisation/podman/default.nix b/nixos/modules/virtualisation/podman/default.nix index 1e2f8a7fae6..47d95d28faf 100644 --- a/nixos/modules/virtualisation/podman/default.nix +++ b/nixos/modules/virtualisation/podman/default.nix @@ -57,24 +57,24 @@ in mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' This option enables Podman, a daemonless container engine for developing, managing, and running OCI Containers on your Linux System. - It is a drop-in replacement for the <command>docker</command> command. + It is a drop-in replacement for the {command}`docker` command. ''; }; dockerSocket.enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Make the Podman socket available in place of the Docker socket, so Docker tools can find the Podman socket. Podman implements the Docker API. - Users must be in the <literal>podman</literal> group in order to connect. As + Users must be in the `podman` group in order to connect. As with Docker, members of this group can gain root access. ''; }; @@ -82,15 +82,15 @@ in dockerCompat = mkOption { type = types.bool; default = false; - description = '' - Create an alias mapping <command>docker</command> to <command>podman</command>. + description = lib.mdDoc '' + Create an alias mapping {command}`docker` to {command}`podman`. ''; }; enableNvidia = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable use of NVidia GPUs from within podman containers. ''; }; @@ -103,7 +103,7 @@ in pkgs.gvisor ] ''; - description = '' + description = lib.mdDoc '' Extra packages to be installed in the Podman wrapper. ''; }; @@ -120,7 +120,7 @@ in defaultNetwork.extraPlugins = lib.mkOption { type = types.listOf json.type; default = []; - description = '' + description = lib.mdDoc '' Extra CNI plugin configurations to add to podman's default network. ''; }; diff --git a/nixos/modules/virtualisation/podman/network-socket.nix b/nixos/modules/virtualisation/podman/network-socket.nix index 5f6ce493558..6e46b9c4556 100644 --- a/nixos/modules/virtualisation/podman/network-socket.nix +++ b/nixos/modules/virtualisation/podman/network-socket.nix @@ -32,7 +32,7 @@ in server = mkOption { type = types.enum []; - description = '' + description = lib.mdDoc '' Choice of TLS proxy server. ''; example = "ghostunnel"; @@ -41,28 +41,28 @@ in openFirewall = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to open the port in the firewall. ''; }; tls.cacert = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to CA certificate to use for client authentication. ''; }; tls.cert = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to certificate describing the server. ''; }; tls.key = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to the private key corresponding to the server certificate. Use a string for this setting. Otherwise it will be copied to the Nix @@ -73,14 +73,14 @@ in port = mkOption { type = types.port; default = 2376; - description = '' + description = lib.mdDoc '' TCP port number for receiving TLS connections. ''; }; listenAddress = mkOption { type = types.str; default = "0.0.0.0"; - description = '' + description = lib.mdDoc '' Interface address for receiving TLS connections. ''; }; diff --git a/nixos/modules/virtualisation/qemu-vm.nix b/nixos/modules/virtualisation/qemu-vm.nix index 98617a397a5..ab007834220 100644 --- a/nixos/modules/virtualisation/qemu-vm.nix +++ b/nixos/modules/virtualisation/qemu-vm.nix @@ -27,26 +27,26 @@ let file = mkOption { type = types.str; - description = "The file image used for this drive."; + description = lib.mdDoc "The file image used for this drive."; }; driveExtraOpts = mkOption { type = types.attrsOf types.str; default = {}; - description = "Extra options passed to drive flag."; + description = lib.mdDoc "Extra options passed to drive flag."; }; deviceExtraOpts = mkOption { type = types.attrsOf types.str; default = {}; - description = "Extra options passed to device flag."; + description = lib.mdDoc "Extra options passed to device flag."; }; name = mkOption { type = types.nullOr types.str; default = null; description = - "A name for the drive. Must be unique in the drives list. Not passed to qemu."; + lib.mdDoc "A name for the drive. Must be unique in the drives list. Not passed to qemu."; }; }; @@ -298,7 +298,7 @@ in type = types.ints.positive; default = 1024; description = - '' + lib.mdDoc '' The memory size in megabytes of the virtual machine. ''; }; @@ -308,7 +308,7 @@ in type = types.ints.positive; default = 16384; description = - '' + lib.mdDoc '' The msize (maximum packet size) option passed to 9p file systems, in bytes. Increasing this should increase performance significantly, at the cost of higher RAM usage. @@ -320,7 +320,7 @@ in type = types.nullOr types.ints.positive; default = 1024; description = - '' + lib.mdDoc '' The disk size in megabytes of the virtual machine. ''; }; @@ -331,7 +331,7 @@ in default = "./${config.system.name}.qcow2"; defaultText = literalExpression ''"./''${config.system.name}.qcow2"''; description = - '' + lib.mdDoc '' Path to the disk image containing the root filesystem. The image will be created on startup if it does not exist. @@ -343,7 +343,7 @@ in type = types.path; example = "/dev/vda"; description = - '' + lib.mdDoc '' The disk to be used for the root filesystem. ''; }; @@ -353,7 +353,7 @@ in type = types.listOf types.ints.positive; default = []; description = - '' + lib.mdDoc '' Additional disk images to provide to the VM. The value is a list of size in megabytes of each disk. These disks are writeable by the VM. @@ -365,7 +365,7 @@ in type = types.bool; default = true; description = - '' + lib.mdDoc '' Whether to run QEMU with a graphics window, or in nographic mode. Serial console will be enabled on both settings, but this will change the preferred console. @@ -377,7 +377,7 @@ in type = options.services.xserver.resolutions.type.nestedTypes.elemType; default = { x = 1024; y = 768; }; description = - '' + lib.mdDoc '' The resolution of the virtual machine display. ''; }; @@ -387,7 +387,7 @@ in type = types.ints.positive; default = 1; description = - '' + lib.mdDoc '' Specify the number of cores the guest is permitted to use. The number can be higher than the available cores on the host system. @@ -400,11 +400,11 @@ in (types.submodule { options.source = mkOption { type = types.str; - description = "The path of the directory to share, can be a shell variable"; + description = lib.mdDoc "The path of the directory to share, can be a shell variable"; }; options.target = mkOption { type = types.path; - description = "The mount point of the directory inside the virtual machine"; + description = lib.mdDoc "The mount point of the directory inside the virtual machine"; }; }); default = { }; @@ -412,7 +412,7 @@ in my-share = { source = "/path/to/be/shared"; target = "/mnt/shared"; }; }; description = - '' + lib.mdDoc '' An attributes set of directories that will be shared with the virtual machine using VirtFS (9P filesystem over VirtIO). The attribute name will be used as the 9P mount tag. @@ -424,7 +424,7 @@ in type = types.listOf types.path; default = []; description = - '' + lib.mdDoc '' A list of paths whose closure should be made available to the VM. @@ -434,7 +434,7 @@ in garbage (because they are not registered in the Nix database of the guest). - When <option>virtualisation.useNixStoreImage</option> is + When {option}`virtualisation.useNixStoreImage` is set, the closure is copied to the Nix store image. ''; }; @@ -459,25 +459,25 @@ in options.proto = mkOption { type = types.enum [ "tcp" "udp" ]; default = "tcp"; - description = "The protocol to forward."; + description = lib.mdDoc "The protocol to forward."; }; options.host.address = mkOption { type = types.str; default = ""; - description = "The IPv4 address of the host."; + description = lib.mdDoc "The IPv4 address of the host."; }; options.host.port = mkOption { type = types.port; - description = "The host port to be mapped."; + description = lib.mdDoc "The host port to be mapped."; }; options.guest.address = mkOption { type = types.str; default = ""; - description = "The IPv4 address on the guest VLAN."; + description = lib.mdDoc "The IPv4 address on the guest VLAN."; }; options.guest.port = mkOption { type = types.port; - description = "The guest port to be mapped."; + description = lib.mdDoc "The guest port to be mapped."; }; }); default = []; @@ -514,13 +514,13 @@ in default = [ 1 ]; example = [ 1 2 ]; description = - '' + lib.mdDoc '' Virtual networks to which the VM is connected. Each number «N» in this list causes the VM to have a virtual Ethernet interface attached to a separate virtual network on which it will be assigned IP address - <literal>192.168.«N».«M»</literal>, + `192.168.«N».«M»`, where «M» is the index of this VM in the list of VMs. ''; @@ -531,7 +531,7 @@ in type = types.bool; default = true; # FIXME description = - '' + lib.mdDoc '' If enabled, the Nix store in the VM is made writable by layering an overlay filesystem on top of the host's Nix store. @@ -543,7 +543,7 @@ in type = types.bool; default = true; description = - '' + lib.mdDoc '' Use a tmpfs for the writable store instead of writing to the VM's own filesystem. ''; @@ -563,7 +563,7 @@ in type = types.package; default = pkgs.qemu_kvm; example = "pkgs.qemu_test"; - description = "QEMU package to use."; + description = lib.mdDoc "QEMU package to use."; }; options = @@ -571,7 +571,7 @@ in type = types.listOf types.str; default = []; example = [ "-vga std" ]; - description = "Options passed to QEMU."; + description = lib.mdDoc "Options passed to QEMU."; }; consoles = mkOption { @@ -580,14 +580,14 @@ in consoles = [ "${qemu-common.qemuSerialDevice},115200n8" "tty0" ]; in if cfg.graphics then consoles else reverseList consoles; example = [ "console=tty1" ]; - description = '' + description = lib.mdDoc '' The output console devices to pass to the kernel command line via the - <literal>console</literal> parameter, the primary console is the last + `console` parameter, the primary console is the last item of this list. By default it enables both serial console and - <literal>tty0</literal>. The preferred console (last one) is based on - the value of <option>virtualisation.graphics</option>. + `tty0`. The preferred console (last one) is based on + the value of {option}`virtualisation.graphics`. ''; }; @@ -599,7 +599,7 @@ in "-net nic,netdev=user.0,model=virtio" "-netdev user,id=user.0,\${QEMU_NET_OPTS:+,$QEMU_NET_OPTS}" ]; - description = '' + description = lib.mdDoc '' Networking-related command-line options that should be passed to qemu. The default is to use userspace networking (SLiRP). @@ -612,7 +612,7 @@ in drives = mkOption { type = types.listOf (types.submodule driveOpts); - description = "Drives passed to qemu."; + description = lib.mdDoc "Drives passed to qemu."; apply = addDeviceNames; }; @@ -621,14 +621,14 @@ in type = types.enum [ "virtio" "scsi" "ide" ]; default = "virtio"; example = "scsi"; - description = "The interface used for the virtual hard disks."; + description = lib.mdDoc "The interface used for the virtual hard disks."; }; guestAgent.enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable the Qemu guest agent. ''; }; @@ -637,7 +637,7 @@ in mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable the virtio-keyboard device. ''; }; @@ -647,7 +647,7 @@ in mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Build and use a disk image for the Nix store, instead of accessing the host's one through 9p. @@ -662,7 +662,7 @@ in type = types.bool; default = false; description = - '' + lib.mdDoc '' If enabled, the virtual machine will be booted using the regular boot loader (i.e., GRUB 1 or 2). This allows testing of the boot loader. If @@ -677,7 +677,7 @@ in type = types.bool; default = false; description = - '' + lib.mdDoc '' If enabled, the virtual machine will provide a EFI boot manager. useEFIBoot is ignored if useBootLoader == false. @@ -689,7 +689,7 @@ in type = types.bool; default = true; description = - '' + lib.mdDoc '' If enabled, the boot disk of the virtual machine will be formatted and mounted with the default filesystems for testing. Swap devices and LUKS will be disabled. @@ -705,7 +705,7 @@ in default = "./${config.system.name}-efi-vars.fd"; defaultText = literalExpression ''"./''${config.system.name}-efi-vars.fd"''; description = - '' + lib.mdDoc '' Path to nvram image containing UEFI variables. The will be created on startup if it does not exist. ''; |