From 36a53d9f26f2ec2530263250e808262bc78fc3be Mon Sep 17 00:00:00 2001 From: Emily Date: Sat, 1 Jul 2023 00:30:13 +0100 Subject: [PATCH] treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]. All conversions were automatically checked to produce the same DocBook result when converted back, modulo minor typographical/formatting differences on the acceptable-to-desirable spectrum. To reproduce this commit, run: $ NIX_PATH=nixpkgs=flake:nixpkgs/e7e69199f0372364a6106a1e735f68604f4c5a25 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run -- github:emilazy/nix-doc-munge/98dadf1f77351c2ba5dcb709a2a171d655f15099 \ {} + $ ./format [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge/tree/home-manager --- modules/accounts/calendar.nix | 30 +- modules/accounts/contacts.nix | 26 +- modules/accounts/email.nix | 108 ++++---- modules/config/home-cursor.nix | 37 +-- modules/config/i18n.nix | 12 +- modules/files.nix | 4 +- modules/home-environment.nix | 172 ++++++------ modules/i18n/input-method/default.nix | 2 +- modules/i18n/input-method/fcitx5.nix | 2 +- modules/i18n/input-method/kime.nix | 4 +- modules/i18n/input-method/uim.nix | 2 +- modules/launchd/default.nix | 12 +- modules/launchd/launchd.nix | 259 +++++++++--------- modules/lib/file-type.nix | 36 +-- modules/lib/types.nix | 8 +- modules/manual.nix | 14 +- modules/misc/dconf.nix | 22 +- modules/misc/editorconfig.nix | 10 +- modules/misc/fontconfig.nix | 6 +- modules/misc/gtk.nix | 57 ++-- modules/misc/lib.nix | 2 +- modules/misc/news.nix | 10 +- modules/misc/nix.nix | 33 ++- modules/misc/nixpkgs.nix | 34 +-- modules/misc/numlock.nix | 4 +- modules/misc/pam.nix | 17 +- modules/misc/qt.nix | 6 +- modules/misc/specialisation.nix | 2 +- modules/misc/submodule-support.nix | 8 +- modules/misc/tmpfiles.nix | 7 +- modules/misc/version.nix | 14 +- modules/misc/xdg-desktop-entries.nix | 46 ++-- modules/misc/xdg-mime-apps.nix | 15 +- modules/misc/xdg-mime.nix | 6 +- modules/misc/xdg-system-dirs.nix | 8 +- modules/misc/xdg-user-dirs.nix | 29 +- modules/misc/xdg.nix | 14 +- modules/misc/xfconf.nix | 12 +- modules/programs/abook.nix | 8 +- modules/programs/aerc-accounts.nix | 36 +-- modules/programs/aerc.nix | 2 +- modules/programs/afew.nix | 7 +- modules/programs/alacritty.nix | 10 +- modules/programs/alot-accounts.nix | 10 +- modules/programs/alot.nix | 38 +-- modules/programs/antidote.nix | 6 +- modules/programs/aria2.nix | 15 +- modules/programs/astroid-accounts.nix | 8 +- modules/programs/astroid.nix | 6 +- modules/programs/atuin.nix | 30 +- modules/programs/autojump.nix | 8 +- modules/programs/autorandr.nix | 75 +++-- modules/programs/bash.nix | 41 ++- modules/programs/bashmount.nix | 8 +- modules/programs/bat.nix | 8 +- modules/programs/beets.nix | 22 +- modules/programs/borgmatic.nix | 26 +- modules/programs/bottom.nix | 14 +- modules/programs/boxxy.nix | 19 +- modules/programs/broot.nix | 15 +- modules/programs/browserpass.nix | 5 +- modules/programs/btop.nix | 12 +- modules/programs/chromium.nix | 36 +-- .../command-not-found/command-not-found.nix | 7 +- modules/programs/comodoro.nix | 7 +- modules/programs/darcs.nix | 6 +- modules/programs/dircolors.nix | 22 +- modules/programs/direnv.nix | 29 +- modules/programs/discocss.nix | 6 +- modules/programs/eclipse.nix | 10 +- modules/programs/emacs.nix | 20 +- modules/programs/eww.nix | 8 +- modules/programs/exa.nix | 15 +- modules/programs/feh.nix | 10 +- modules/programs/firefox.nix | 67 ++--- modules/programs/fish.nix | 61 +++-- modules/programs/foot.nix | 11 +- modules/programs/fuzzel.nix | 9 +- modules/programs/fzf.nix | 42 +-- modules/programs/gallery-dl.nix | 8 +- modules/programs/getmail-accounts.nix | 21 +- modules/programs/gh.nix | 21 +- modules/programs/git-cliff.nix | 8 +- modules/programs/git-credential-oauth.nix | 3 +- modules/programs/git.nix | 91 +++--- modules/programs/gitui.nix | 14 +- modules/programs/gnome-terminal.nix | 59 ++-- modules/programs/go.nix | 24 +- modules/programs/gpg.nix | 65 ++--- modules/programs/havoc.nix | 7 +- modules/programs/helix.nix | 34 +-- modules/programs/hexchat.nix | 54 ++-- modules/programs/himalaya.nix | 32 ++- modules/programs/home-manager.nix | 10 +- modules/programs/hstr.nix | 8 +- modules/programs/htop.nix | 8 +- modules/programs/hyfetch.nix | 6 +- modules/programs/i3status-rust.nix | 40 ++- modules/programs/i3status.nix | 37 +-- modules/programs/imv.nix | 11 +- modules/programs/info.nix | 2 +- modules/programs/ion.nix | 9 +- modules/programs/irssi.nix | 40 +-- modules/programs/java.nix | 4 +- modules/programs/joshuto.nix | 36 +-- modules/programs/jq.nix | 6 +- modules/programs/jujutsu.nix | 16 +- modules/programs/k9s.nix | 16 +- modules/programs/kakoune.nix | 161 +++++------ modules/programs/keychain.nix | 24 +- modules/programs/khal-accounts.nix | 4 +- modules/programs/khal-calendar-accounts.nix | 8 +- modules/programs/kitty.nix | 44 +-- modules/programs/kodi.nix | 34 +-- modules/programs/lazygit.nix | 13 +- modules/programs/ledger.nix | 13 +- modules/programs/less.nix | 8 +- modules/programs/lesspipe.nix | 2 +- modules/programs/lf.nix | 20 +- modules/programs/librewolf.nix | 10 +- modules/programs/lieer.nix | 55 ++-- modules/programs/looking-glass-client.nix | 4 +- modules/programs/lsd.nix | 10 +- modules/programs/man.nix | 22 +- modules/programs/mangohud.nix | 18 +- modules/programs/matplotlib.nix | 11 +- modules/programs/mbsync-accounts.nix | 66 ++--- modules/programs/mbsync.nix | 9 +- modules/programs/mcfly.nix | 14 +- modules/programs/mercurial.nix | 17 +- modules/programs/micro.nix | 8 +- modules/programs/mpv.nix | 45 ++- modules/programs/mr.nix | 8 +- modules/programs/msmtp-accounts.nix | 24 +- modules/programs/msmtp.nix | 18 +- modules/programs/mu.nix | 7 +- modules/programs/mujmap.nix | 134 ++++----- modules/programs/navi.nix | 18 +- modules/programs/ncmpcpp.nix | 32 +-- modules/programs/ncspot.nix | 12 +- modules/programs/ne.nix | 16 +- modules/programs/neomutt-accounts.nix | 20 +- modules/programs/neomutt.nix | 41 +-- modules/programs/neovim.nix | 74 +++-- modules/programs/newsboat.nix | 26 +- modules/programs/nheko.nix | 10 +- modules/programs/nix-index.nix | 12 +- modules/programs/nnn.nix | 18 +- modules/programs/noti.nix | 13 +- modules/programs/notmuch-virtual-mailbox.nix | 9 +- modules/programs/notmuch.nix | 29 +- modules/programs/nushell.nix | 43 ++- modules/programs/obs-studio.nix | 8 +- modules/programs/octant.nix | 6 +- modules/programs/offlineimap-accounts.nix | 10 +- modules/programs/offlineimap.nix | 16 +- modules/programs/oh-my-posh.nix | 23 +- modules/programs/opam.nix | 10 +- modules/programs/pandoc.nix | 14 +- modules/programs/papis.nix | 16 +- modules/programs/password-store.nix | 17 +- modules/programs/pazi.nix | 8 +- modules/programs/pet.nix | 20 +- modules/programs/pidgin.nix | 6 +- modules/programs/pistol.nix | 16 +- modules/programs/piston-cli.nix | 8 +- modules/programs/pls.nix | 4 +- modules/programs/powerline-go.nix | 21 +- modules/programs/pubs.nix | 8 +- modules/programs/pyenv.nix | 10 +- modules/programs/pylint.nix | 6 +- modules/programs/pywal.nix | 4 +- modules/programs/qutebrowser.nix | 46 ++-- modules/programs/rbenv.nix | 20 +- modules/programs/rbw.nix | 30 +- modules/programs/readline.nix | 13 +- modules/programs/ripgrep.nix | 8 +- modules/programs/rofi-pass.nix | 8 +- modules/programs/rofi.nix | 32 +-- modules/programs/rtorrent.nix | 8 +- modules/programs/rtx.nix | 23 +- modules/programs/sagemath.nix | 21 +- modules/programs/sbt.nix | 48 ++-- modules/programs/scmpuff.nix | 12 +- modules/programs/script-directory.nix | 2 +- modules/programs/senpai.nix | 17 +- modules/programs/sioyek.nix | 20 +- modules/programs/skim.nix | 24 +- modules/programs/sm64ex.nix | 16 +- modules/programs/sqls.nix | 9 +- modules/programs/ssh.nix | 154 +++++------ modules/programs/starship.nix | 29 +- modules/programs/swaylock.nix | 6 +- modules/programs/taskwarrior.nix | 16 +- modules/programs/tealdeer.nix | 10 +- modules/programs/terminator.nix | 14 +- modules/programs/termite.nix | 97 +++---- modules/programs/texlive.nix | 8 +- modules/programs/thunderbird.nix | 43 +-- modules/programs/timidity.nix | 9 +- modules/programs/tint2.nix | 10 +- modules/programs/tiny.nix | 11 +- modules/programs/tmate.nix | 16 +- modules/programs/tmux.nix | 62 +++-- modules/programs/topgrade.nix | 12 +- modules/programs/translate-shell.nix | 8 +- modules/programs/urxvt.nix | 36 +-- modules/programs/vdirsyncer-accounts.nix | 64 ++--- modules/programs/vdirsyncer.nix | 4 +- modules/programs/vim-vint.nix | 6 +- modules/programs/vim.nix | 20 +- modules/programs/vscode.nix | 37 +-- modules/programs/vscode/haskell.nix | 6 +- modules/programs/watson.nix | 36 +-- modules/programs/waybar.nix | 65 +++-- modules/programs/wezterm.nix | 30 +- modules/programs/wlogout.nix | 31 +-- modules/programs/wofi.nix | 18 +- modules/programs/xmobar.nix | 12 +- modules/programs/yt-dlp.nix | 20 +- modules/programs/z-lua.nix | 12 +- modules/programs/zathura.nix | 30 +- modules/programs/zellij.nix | 18 +- modules/programs/zoxide.nix | 14 +- modules/programs/zplug.nix | 10 +- modules/programs/zsh.nix | 112 ++++---- modules/programs/zsh/prezto.nix | 66 ++--- modules/services/autorandr.nix | 2 +- modules/services/avizo.nix | 6 +- modules/services/barrier.nix | 20 +- modules/services/batsignal.nix | 4 +- modules/services/betterlockscreen.nix | 14 +- modules/services/borgmatic.nix | 11 +- modules/services/cachix-agent.nix | 16 +- modules/services/caffeine.nix | 4 +- modules/services/cbatticon.nix | 16 +- modules/services/clipman.nix | 12 +- modules/services/clipmenu.nix | 9 +- modules/services/comodoro.nix | 8 +- modules/services/copyq.nix | 13 +- modules/services/devilspie2.nix | 6 +- modules/services/dropbox.nix | 4 +- modules/services/dunst.nix | 28 +- modules/services/dwm-status.nix | 8 +- modules/services/easyeffects.nix | 12 +- modules/services/emacs.nix | 34 +-- modules/services/espanso.nix | 13 +- modules/services/etesync-dav.nix | 8 +- modules/services/flameshot.nix | 8 +- modules/services/fluidsynth.nix | 13 +- modules/services/fnott.nix | 30 +- modules/services/fusuma.nix | 10 +- modules/services/getmail.nix | 10 +- modules/services/git-sync.nix | 18 +- modules/services/gnome-keyring.nix | 4 +- modules/services/gpg-agent.nix | 50 ++-- modules/services/grobi.nix | 16 +- modules/services/gromit-mpx.nix | 30 +- .../services/home-manager-auto-upgrade.nix | 13 +- modules/services/hound.nix | 10 +- modules/services/imapnotify-accounts.nix | 11 +- modules/services/imapnotify.nix | 4 +- modules/services/kanshi.nix | 39 ++- modules/services/kbfs.nix | 8 +- modules/services/kdeconnect.nix | 5 +- modules/services/keepassx.nix | 2 +- modules/services/keybase.nix | 2 +- modules/services/keynav.nix | 2 +- modules/services/lieer.nix | 2 +- modules/services/listenbrainz-mpd.nix | 6 +- modules/services/lorri.nix | 9 +- modules/services/mako.nix | 68 ++--- modules/services/mbsync.nix | 21 +- modules/services/megasync.nix | 2 +- modules/services/mopidy.nix | 14 +- modules/services/mpd-discord-rpc.nix | 10 +- modules/services/mpd-mpris.nix | 19 +- modules/services/mpd.nix | 39 ++- modules/services/mpdris2.nix | 17 +- modules/services/mpris-proxy.nix | 4 +- modules/services/muchsync.nix | 49 ++-- modules/services/network-manager-applet.nix | 2 +- modules/services/nextcloud-client.nix | 7 +- modules/services/notify-osd.nix | 6 +- modules/services/opensnitch-ui.nix | 4 +- modules/services/owncloud-client.nix | 2 +- modules/services/pantalaimon.nix | 21 +- modules/services/parcellite.nix | 6 +- modules/services/pass-secret-service.nix | 10 +- modules/services/password-store-sync.nix | 13 +- modules/services/pasystray.nix | 4 +- modules/services/pbgopy.nix | 10 +- modules/services/picom.nix | 46 ++-- modules/services/plan9port.nix | 6 +- modules/services/playerctld.nix | 4 +- modules/services/plex-mpv-shim.nix | 10 +- modules/services/polybar.nix | 14 +- modules/services/poweralertd.nix | 2 +- modules/services/pueue.nix | 7 +- modules/services/pulseeffects.nix | 12 +- modules/services/random-background.nix | 9 +- modules/services/recoll.nix | 26 +- .../redshift-gammastep/lib/options.nix | 45 ++- modules/services/rsibreak.nix | 2 +- modules/services/safeeyes.nix | 2 +- modules/services/screen-locker.nix | 40 +-- modules/services/sctd.nix | 9 +- modules/services/spotifyd.nix | 8 +- modules/services/ssh-agent.nix | 2 +- modules/services/stalonetray.nix | 10 +- modules/services/status-notifier-watcher.nix | 4 +- modules/services/swayidle.nix | 24 +- modules/services/swayosd.nix | 6 +- modules/services/sxhkd.nix | 11 +- modules/services/syncthing.nix | 16 +- modules/services/systembus-notify.nix | 4 +- modules/services/taffybar.nix | 4 +- modules/services/tahoe-lafs.nix | 2 +- modules/services/taskwarrior-sync.nix | 13 +- modules/services/trayer.nix | 4 +- modules/services/twmn.nix | 82 +++--- modules/services/udiskie.nix | 12 +- modules/services/unclutter.nix | 13 +- modules/services/unison.nix | 21 +- modules/services/vdirsyncer.nix | 17 +- modules/services/volnoti.nix | 6 +- modules/services/window-managers/awesome.nix | 8 +- .../window-managers/bspwm/options.nix | 68 ++--- modules/services/window-managers/fluxbox.nix | 52 ++-- .../services/window-managers/herbstluftwm.nix | 22 +- .../services/window-managers/i3-sway/i3.nix | 16 +- .../window-managers/i3-sway/lib/options.nix | 202 +++++++------- .../services/window-managers/i3-sway/sway.nix | 74 +++-- .../window-managers/i3-sway/swaynag.nix | 17 +- modules/services/window-managers/spectrwm.nix | 16 +- modules/services/window-managers/xmonad.nix | 31 +-- modules/services/wlsunset.nix | 28 +- modules/services/xcape.nix | 20 +- modules/services/xembed-sni-proxy.nix | 6 +- modules/services/xidlehook.nix | 31 ++- modules/services/xscreensaver.nix | 4 +- modules/services/xsettingsd.nix | 10 +- modules/services/xsuspender.nix | 36 +-- modules/systemd.nix | 13 +- modules/targets/darwin/keybindings.nix | 12 +- modules/targets/darwin/search.nix | 2 +- .../targets/darwin/user-defaults/default.nix | 30 +- .../darwin/user-defaults/opts-allhosts.nix | 59 ++-- .../darwin/user-defaults/opts-currenthost.nix | 4 +- modules/xresources.nix | 16 +- modules/xsession.nix | 28 +- nixos/common.nix | 2 +- tests/asserts.nix | 8 +- tests/big-test.nix | 2 +- tests/stubs.nix | 4 +- 355 files changed, 3805 insertions(+), 3886 deletions(-) diff --git a/modules/accounts/calendar.nix b/modules/accounts/calendar.nix index e96f2f2d..c38dbee5 100644 --- a/modules/accounts/calendar.nix +++ b/modules/accounts/calendar.nix @@ -13,24 +13,24 @@ let type = types.str; default = "${cfg.basePath}/${name}"; defaultText = "‹accounts.calendar.basePath›/‹name›"; - description = "The path of the storage."; + description = lib.mdDoc "The path of the storage."; }; type = mkOption { type = types.enum [ "filesystem" "singlefile" ]; - description = "The type of the storage."; + description = lib.mdDoc "The type of the storage."; }; fileExt = mkOption { type = types.nullOr types.str; default = null; - description = "The file extension to use."; + description = lib.mdDoc "The file extension to use."; }; encoding = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' File encoding for items, both content and file name. Defaults to UTF-8. ''; @@ -42,19 +42,19 @@ let options = { type = mkOption { type = types.enum [ "caldav" "http" "google_calendar" ]; - description = "The type of the storage."; + description = lib.mdDoc "The type of the storage."; }; url = mkOption { type = types.nullOr types.str; default = null; - description = "The URL of the storage."; + description = lib.mdDoc "The URL of the storage."; }; userName = mkOption { type = types.nullOr types.str; default = null; - description = "User name for authentication."; + description = lib.mdDoc "User name for authentication."; }; # userNameCommand = mkOption { @@ -70,7 +70,7 @@ let type = types.nullOr (types.listOf types.str); default = null; example = [ "pass" "caldav" ]; - description = '' + description = lib.mdDoc '' A command that prints the password to standard output. ''; }; @@ -82,7 +82,7 @@ let name = mkOption { type = types.str; readOnly = true; - description = '' + description = lib.mdDoc '' Unique identifier of the calendar. This is set to the attribute name of the calendar configuration. ''; @@ -91,7 +91,7 @@ let primary = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether this is the primary account. Only one account may be set as primary. ''; @@ -99,7 +99,7 @@ let primaryCollection = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The primary collection of the account. Required when an account has multiple collections. ''; @@ -108,7 +108,7 @@ let local = mkOption { type = types.nullOr (localModule name); default = null; - description = '' + description = lib.mdDoc '' Local configuration for the calendar. ''; }; @@ -116,7 +116,7 @@ let remote = mkOption { type = types.nullOr remoteModule; default = null; - description = '' + description = lib.mdDoc '' Remote configuration for the calendar. ''; }; @@ -131,7 +131,7 @@ in { type = types.str; apply = p: if hasPrefix "/" p then p else "${config.home.homeDirectory}/${p}"; - description = '' + description = lib.mdDoc '' The base directory in which to save calendars. May be a relative path, in which case it is relative the home directory. @@ -146,7 +146,7 @@ in { (import ../programs/khal-calendar-accounts.nix) ]); default = { }; - description = "List of calendars."; + description = lib.mdDoc "List of calendars."; }; }; config = mkIf (cfg.accounts != { }) { diff --git a/modules/accounts/contacts.nix b/modules/accounts/contacts.nix index 83f57d8e..6f117d0b 100644 --- a/modules/accounts/contacts.nix +++ b/modules/accounts/contacts.nix @@ -13,24 +13,24 @@ let type = types.str; default = "${cfg.basePath}/${name}"; defaultText = "‹accounts.contact.basePath›/‹name›"; - description = "The path of the storage."; + description = lib.mdDoc "The path of the storage."; }; type = mkOption { type = types.enum [ "filesystem" "singlefile" ]; - description = "The type of the storage."; + description = lib.mdDoc "The type of the storage."; }; fileExt = mkOption { type = types.nullOr types.str; default = null; - description = "The file extension to use."; + description = lib.mdDoc "The file extension to use."; }; encoding = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' File encoding for items, both content and file name. Defaults to UTF-8. ''; @@ -42,19 +42,19 @@ let options = { type = mkOption { type = types.enum [ "carddav" "http" "google_contacts" ]; - description = "The type of the storage."; + description = lib.mdDoc "The type of the storage."; }; url = mkOption { type = types.nullOr types.str; default = null; - description = "The URL of the storage."; + description = lib.mdDoc "The URL of the storage."; }; userName = mkOption { type = types.nullOr types.str; default = null; - description = "User name for authentication."; + description = lib.mdDoc "User name for authentication."; }; # userNameCommand = mkOption { @@ -70,7 +70,7 @@ let type = types.nullOr (types.listOf types.str); default = null; example = [ "pass" "caldav" ]; - description = '' + description = lib.mdDoc '' A command that prints the password to standard output. ''; }; @@ -82,7 +82,7 @@ let name = mkOption { type = types.str; readOnly = true; - description = '' + description = lib.mdDoc '' Unique identifier of the contact account. This is set to the attribute name of the contact configuration. ''; @@ -91,7 +91,7 @@ let local = mkOption { type = types.nullOr (localModule name); default = null; - description = '' + description = lib.mdDoc '' Local configuration for the contacts. ''; }; @@ -99,7 +99,7 @@ let remote = mkOption { type = types.nullOr remoteModule; default = null; - description = '' + description = lib.mdDoc '' Remote configuration for the contacts. ''; }; @@ -114,7 +114,7 @@ in { type = types.str; apply = p: if hasPrefix "/" p then p else "${config.home.homeDirectory}/${p}"; - description = '' + description = lib.mdDoc '' The base directory in which to save contacts. May be a relative path, in which case it is relative the home directory. @@ -128,7 +128,7 @@ in { (import ../programs/khal-accounts.nix) ]); default = { }; - description = "List of contacts."; + description = lib.mdDoc "List of contacts."; }; }; } diff --git a/modules/accounts/email.nix b/modules/accounts/email.nix index ed7ae55e..63a6b10e 100644 --- a/modules/accounts/email.nix +++ b/modules/accounts/email.nix @@ -10,21 +10,21 @@ let options = { key = mkOption { type = types.str; - description = '' - The key to use as listed in gpg --list-keys. + description = lib.mdDoc '' + The key to use as listed in {command}`gpg --list-keys`. ''; }; signByDefault = mkOption { type = types.bool; default = false; - description = "Sign messages by default."; + description = lib.mdDoc "Sign messages by default."; }; encryptByDefault = mkOption { type = types.bool; default = false; - description = "Encrypt outgoing messages by default."; + description = lib.mdDoc "Encrypt outgoing messages by default."; }; }; }; @@ -39,7 +39,7 @@ let Luke Skywalker May the force be with you. ''; - description = '' + description = lib.mdDoc '' Signature content. ''; }; @@ -52,7 +52,7 @@ let example = literalExpression '' ~*~*~*~*~*~*~*~*~*~*~*~ ''; - description = '' + description = lib.mdDoc '' The delimiter used between the document and the signature. ''; }; @@ -63,13 +63,13 @@ let example = literalExpression '' pkgs.writeScript "signature" "echo This is my signature" ''; - description = "A command that generates a signature."; + description = lib.mdDoc "A command that generates a signature."; }; showSignature = mkOption { type = types.enum [ "append" "attach" "none" ]; default = "none"; - description = "Method to communicate the signature."; + description = lib.mdDoc "Method to communicate the signature."; }; }; }; @@ -79,7 +79,7 @@ let enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable TLS/SSL. ''; }; @@ -87,7 +87,7 @@ let useStartTls = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to use STARTTLS. ''; }; @@ -96,10 +96,10 @@ let type = types.nullOr types.path; default = config.accounts.email.certificatesFile; defaultText = "config.accounts.email.certificatesFile"; - description = '' + description = lib.mdDoc '' Path to file containing certificate authorities that should be used to validate the connection authenticity. If - null then the system default is used. + `null` then the system default is used. Note, if set then the system default may still be accepted. ''; }; @@ -111,7 +111,7 @@ let host = mkOption { type = types.str; example = "imap.example.org"; - description = '' + description = lib.mdDoc '' Hostname of IMAP server. ''; }; @@ -120,16 +120,16 @@ let type = types.nullOr types.port; default = null; example = 993; - description = '' + description = lib.mdDoc '' The port on which the IMAP server listens. If - null then the default port is used. + `null` then the default port is used. ''; }; tls = mkOption { type = tlsModule; default = { }; - description = '' + description = lib.mdDoc '' Configuration for secure connections. ''; }; @@ -142,12 +142,11 @@ let type = types.nullOr types.str; default = null; example = "jmap.example.org"; - description = '' + description = lib.mdDoc '' Hostname of JMAP server. - - If both this option and are specified, - host is preferred by applications when establishing a + + If both this option and [](#opt-accounts.email.accounts._name_.jmap.sessionUrl) are specified, + `host` is preferred by applications when establishing a session. ''; }; @@ -156,12 +155,11 @@ let type = types.nullOr types.str; default = null; example = "https://jmap.example.org:443/.well-known/jmap"; - description = '' + description = lib.mdDoc '' URL for the JMAP Session resource. - - If both this option and are specified, - host is preferred by applications when establishing a + + If both this option and [](#opt-accounts.email.accounts._name_.jmap.host) are specified, + `host` is preferred by applications when establishing a session. ''; }; @@ -173,7 +171,7 @@ let host = mkOption { type = types.str; example = "smtp.example.org"; - description = '' + description = lib.mdDoc '' Hostname of SMTP server. ''; }; @@ -182,16 +180,16 @@ let type = types.nullOr types.port; default = null; example = 465; - description = '' + description = lib.mdDoc '' The port on which the SMTP server listens. If - null then the default port is used. + `null` then the default port is used. ''; }; tls = mkOption { type = tlsModule; default = { }; - description = '' + description = lib.mdDoc '' Configuration for secure connections. ''; }; @@ -202,7 +200,7 @@ let options = { path = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Path to maildir directory where mail for this account is stored. This is relative to the base maildir path. ''; @@ -213,7 +211,7 @@ let readOnly = true; internal = true; default = "${cfg.maildirBasePath}/${config.path}"; - description = '' + description = lib.mdDoc '' A convenience option whose value is the absolute path of this maildir. ''; @@ -226,7 +224,7 @@ let name = mkOption { type = types.str; readOnly = true; - description = '' + description = lib.mdDoc '' Unique identifier of the account. This is set to the attribute name of the account configuration. ''; @@ -235,7 +233,7 @@ let primary = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether this is the primary account. Only one account may be set as primary. ''; @@ -251,11 +249,11 @@ let "outlook.office365.com" ]; default = "plain"; - description = '' + description = lib.mdDoc '' Some email providers have peculiar behavior that require special treatment. This option is therefore intended to indicate the nature of the provider. - + When this indicates a specific provider then, for example, the IMAP, SMTP, and JMAP server configuration may be set automatically. @@ -265,26 +263,26 @@ let address = mkOption { type = types.strMatching ".*@.*"; example = "jane.doe@example.org"; - description = "The email address of this account."; + description = lib.mdDoc "The email address of this account."; }; aliases = mkOption { type = types.listOf (types.strMatching ".*@.*"); default = [ ]; example = [ "webmaster@example.org" "admin@example.org" ]; - description = "Alternative email addresses of this account."; + description = lib.mdDoc "Alternative email addresses of this account."; }; realName = mkOption { type = types.str; example = "Jane Doe"; - description = "Name displayed when sending mails."; + description = lib.mdDoc "Name displayed when sending mails."; }; userName = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The server username of this account. This will be used as the SMTP, IMAP, and JMAP user name. ''; @@ -295,7 +293,7 @@ let default = null; apply = p: if isString p then splitString " " p else p; example = "secret-tool lookup email me@example.org"; - description = '' + description = lib.mdDoc '' A command, which when run writes the account password on standard output. ''; @@ -307,7 +305,7 @@ let inbox = mkOption { type = types.str; default = "Inbox"; - description = '' + description = lib.mdDoc '' Relative path of the inbox mail. ''; }; @@ -315,7 +313,7 @@ let sent = mkOption { type = types.nullOr types.str; default = "Sent"; - description = '' + description = lib.mdDoc '' Relative path of the sent mail folder. ''; }; @@ -323,7 +321,7 @@ let drafts = mkOption { type = types.nullOr types.str; default = "Drafts"; - description = '' + description = lib.mdDoc '' Relative path of the drafts mail folder. ''; }; @@ -331,14 +329,14 @@ let trash = mkOption { type = types.str; default = "Trash"; - description = '' + description = lib.mdDoc '' Relative path of the deleted mail folder. ''; }; }; }; default = { }; - description = '' + description = lib.mdDoc '' Standard email folders. ''; }; @@ -346,7 +344,7 @@ let imap = mkOption { type = types.nullOr imapModule; default = null; - description = '' + description = lib.mdDoc '' The IMAP configuration to use for this account. ''; }; @@ -354,7 +352,7 @@ let jmap = mkOption { type = types.nullOr jmapModule; default = null; - description = '' + description = lib.mdDoc '' The JMAP configuration to use for this account. ''; }; @@ -362,7 +360,7 @@ let signature = mkOption { type = signatureModule; default = { }; - description = '' + description = lib.mdDoc '' Signature configuration. ''; }; @@ -370,7 +368,7 @@ let gpg = mkOption { type = types.nullOr gpgModule; default = null; - description = '' + description = lib.mdDoc '' GPG configuration. ''; }; @@ -378,7 +376,7 @@ let smtp = mkOption { type = types.nullOr smtpModule; default = null; - description = '' + description = lib.mdDoc '' The SMTP configuration to use for this account. ''; }; @@ -386,7 +384,7 @@ let maildir = mkOption { type = types.nullOr maildirModule; defaultText = { path = "\${name}"; }; - description = '' + description = lib.mdDoc '' Maildir configuration for this account. ''; }; @@ -479,7 +477,7 @@ in { certificatesFile = mkOption { type = types.nullOr types.path; default = "/etc/ssl/certs/ca-certificates.crt"; - description = '' + description = lib.mdDoc '' Path to default file containing certificate authorities that should be used to validate the connection authenticity. This path may be overridden on a per-account basis. @@ -492,7 +490,7 @@ in { defaultText = "$HOME/Maildir"; apply = p: if hasPrefix "/" p then p else "${config.home.homeDirectory}/${p}"; - description = '' + description = lib.mdDoc '' The base directory for account maildir directories. May be a relative path, in which case it is relative the home directory. @@ -502,7 +500,7 @@ in { accounts = mkOption { type = types.attrsOf (types.submodule mailAccountOpts); default = { }; - description = "List of email accounts."; + description = lib.mdDoc "List of email accounts."; }; }; diff --git a/modules/config/home-cursor.nix b/modules/config/home-cursor.nix index 6c6e128a..0645f128 100644 --- a/modules/config/home-cursor.nix +++ b/modules/config/home-cursor.nix @@ -11,39 +11,40 @@ let package = mkOption { type = types.package; example = literalExpression "pkgs.vanilla-dmz"; - description = "Package providing the cursor theme."; + description = lib.mdDoc "Package providing the cursor theme."; }; name = mkOption { type = types.str; example = "Vanilla-DMZ"; - description = "The cursor name within the package."; + description = lib.mdDoc "The cursor name within the package."; }; size = mkOption { type = types.int; default = 32; example = 64; - description = "The cursor size."; + description = lib.mdDoc "The cursor size."; }; x11 = { - enable = mkEnableOption '' - x11 config generation for - ''; + enable = mkEnableOption (lib.mdDoc '' + x11 config generation for {option}`home.pointerCursor` + ''); defaultCursor = mkOption { type = types.str; default = "left_ptr"; example = "X_cursor"; - description = "The default cursor file to use within the package."; + description = + lib.mdDoc "The default cursor file to use within the package."; }; }; gtk = { - enable = mkEnableOption '' - gtk config generation for - ''; + enable = mkEnableOption (lib.mdDoc '' + gtk config generation for {option}`home.pointerCursor` + ''); }; }; }; @@ -94,21 +95,21 @@ in { home.pointerCursor = mkOption { type = types.nullOr pointerCursorModule; default = null; - description = '' - Cursor configuration. Set to null to disable. - + description = lib.mdDoc '' + Cursor configuration. Set to `null` to disable. + Top-level options declared under this submodule are backend independent - options. Options declared under namespaces such as x11 + options. Options declared under namespaces such as `x11` are backend specific options. By default, only backend independent cursor configurations are generated. If you need configurations for specific backends, you can toggle them via the enable option. For example, - + [](#opt-home.pointerCursor.x11.enable) will enable x11 cursor configurations. - + Note that this will merely generate the cursor configurations. To apply the configurations, the relevant subsytems must also be configured. - For example, will generate - the gtk cursor configuration, but needs + For example, [](#opt-home.pointerCursor.gtk.enable) will generate + the gtk cursor configuration, but [](#opt-gtk.enable) needs to be set for it to be applied. ''; }; diff --git a/modules/config/i18n.nix b/modules/config/i18n.nix index d5619afb..7cb12d7c 100644 --- a/modules/config/i18n.nix +++ b/modules/config/i18n.nix @@ -40,14 +40,14 @@ in { options = { i18n.glibcLocales = mkOption { type = types.path; - description = '' - Customized glibcLocales package providing - the LOCALE_ARCHIVE_* environment variable. - + description = lib.mdDoc '' + Customized `glibcLocales` package providing + the `LOCALE_ARCHIVE_*` environment variable. + This option only applies to the Linux platform. - + When Home Manager is configured with NixOS, the default value - will be set to i18n.glibcLocales from the + will be set to {var}`i18n.glibcLocales` from the system configuration. ''; example = literalExpression '' diff --git a/modules/files.nix b/modules/files.nix index c869df1d..44de392a 100644 --- a/modules/files.nix +++ b/modules/files.nix @@ -26,7 +26,7 @@ in { options = { home.file = mkOption { - description = "Attribute set of files to link into the user home."; + description = lib.mdDoc "Attribute set of files to link into the user home."; default = {}; type = fileType "home.file" "{env}`HOME`" homeDirectory; }; @@ -34,7 +34,7 @@ in home-files = mkOption { type = types.package; internal = true; - description = "Package to contain all home files"; + description = lib.mdDoc "Package to contain all home files"; }; }; diff --git a/modules/home-environment.nix b/modules/home-environment.nix index c2ea3f87..c3c3aa53 100644 --- a/modules/home-environment.nix +++ b/modules/home-environment.nix @@ -13,7 +13,7 @@ let base = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use unless overridden by a more specific option. ''; }; @@ -21,7 +21,7 @@ let ctype = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Character classification category. ''; }; @@ -29,7 +29,7 @@ let numeric = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for numerical values. ''; }; @@ -37,7 +37,7 @@ let time = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for formatting times. ''; }; @@ -45,7 +45,7 @@ let collate = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for collation (alphabetical ordering). ''; }; @@ -53,7 +53,7 @@ let monetary = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for formatting currencies and money amounts. ''; }; @@ -61,7 +61,7 @@ let messages = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for messages, application UI languages, etc. ''; }; @@ -69,7 +69,7 @@ let paper = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for paper sizes. ''; }; @@ -77,7 +77,7 @@ let name = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for personal names. ''; }; @@ -85,7 +85,7 @@ let address = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for addresses. ''; }; @@ -93,7 +93,7 @@ let telephone = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for telephone numbers. ''; }; @@ -101,7 +101,7 @@ let measurement = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The language to use for measurement values. ''; }; @@ -118,12 +118,12 @@ let then null else "us"; defaultText = literalExpression "null"; - description = '' - Keyboard layout. If null, then the system + description = lib.mdDoc '' + Keyboard layout. If `null`, then the system configuration will be used. - - This defaults to null for state - version ≥ 19.09 and "us" otherwise. + + This defaults to `null` for state + version ≥ 19.09 and `"us"` otherwise. ''; }; @@ -131,7 +131,7 @@ let type = with types; nullOr str; default = null; example = "presario"; - description = '' + description = lib.mdDoc '' Keyboard model. ''; }; @@ -140,7 +140,7 @@ let type = types.listOf types.str; default = []; example = ["grp:caps_toggle" "grp_led:scroll"]; - description = '' + description = lib.mdDoc '' X keyboard options; layout switching goes here. ''; }; @@ -153,12 +153,12 @@ let else ""; defaultText = literalExpression "null"; example = "colemak"; - description = '' - X keyboard variant. If null, then the + description = lib.mdDoc '' + X keyboard variant. If `null`, then the system configuration will be used. - - This defaults to null for state - version ≥ 19.09 and "" otherwise. + + This defaults to `null` for state + version ≥ 19.09 and `""` otherwise. ''; }; }; @@ -189,7 +189,7 @@ in undefined for state version ≥ 20.09 ''; example = "jane.doe"; - description = "The user's username."; + description = lib.mdDoc "The user's username."; }; home.homeDirectory = mkOption { @@ -200,7 +200,7 @@ in ''; apply = toString; example = "/home/jane.doe"; - description = "The user's home directory. Must be an absolute path."; + description = lib.mdDoc "The user's home directory. Must be an absolute path."; }; home.profileDirectory = mkOption { @@ -210,7 +210,7 @@ in "/etc/profiles/per-user/''${home.username}" ''; readOnly = true; - description = '' + description = lib.mdDoc '' The profile directory where Home Manager generations are installed. ''; }; @@ -218,7 +218,7 @@ in home.language = mkOption { type = languageSubModule; default = {}; - description = "Language configuration."; + description = lib.mdDoc "Language configuration."; }; home.keyboard = mkOption { @@ -228,8 +228,8 @@ in "{ }" for state version < 21.11, "null" for state version ≥ 21.11 ''; - description = '' - Keyboard configuration. Set to null to + description = lib.mdDoc '' + Keyboard configuration. Set to `null` to disable Home Manager keyboard management. ''; }; @@ -243,14 +243,14 @@ in "..." = "cd ../.."; } ''; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. - + This option should only be used to manage simple aliases that are compatible across all shells. If you need to use a shell specific feature then make sure to use a shell specific option, for example - for Bash. + [](#opt-programs.bash.shellAliases) for Bash. ''; }; @@ -258,45 +258,45 @@ in default = {}; type = with types; lazyAttrsOf (oneOf [ str path int float ]); example = { EDITOR = "emacs"; GS_OPTIONS = "-sPAPERSIZE=a4"; }; - description = '' + description = lib.mdDoc '' Environment variables to always set at login. - + The values may refer to other environment variables using POSIX.2 style variable references. For example, a variable - parameter may be referenced as - $parameter or ''${parameter}. A - default value foo may be given as per - ''${parameter:-foo} and, similarly, an alternate - value bar can be given as per - ''${parameter:+bar}. - + {var}`parameter` may be referenced as + `$parameter` or `''${parameter}`. A + default value `foo` may be given as per + `''${parameter:-foo}` and, similarly, an alternate + value `bar` can be given as per + `''${parameter:+bar}`. + Note, these variables may be set in any order so no session variable may have a runtime dependency on another session variable. In particular code like - + ```nix home.sessionVariables = { FOO = "Hello"; BAR = "$FOO World!"; }; - + ``` may not work as expected. If you need to reference another session variable, then do so inside Nix instead. The above example then becomes - + ```nix home.sessionVariables = { FOO = "Hello"; BAR = "''${config.home.sessionVariables.FOO} World!"; }; - + ``` ''; }; home.sessionVariablesPackage = mkOption { type = types.package; internal = true; - description = '' + description = lib.mdDoc '' The package containing the - hm-session-vars.sh file. + {file}`hm-session-vars.sh` file. ''; }; @@ -308,15 +308,13 @@ in "\${xdg.configHome}/emacs/bin" ".git/safe/../../bin" ]; - description = '' - Extra directories to add to PATH. + description = lib.mdDoc '' + Extra directories to add to {env}`PATH`. - - - These directories are added to the PATH variable in a - double-quoted context, so expressions like $HOME are - expanded by the shell. However, since expressions like ~ or - * are escaped, they will end up in the PATH + These directories are added to the {env}`PATH` variable in a + double-quoted context, so expressions like `$HOME` are + expanded by the shell. However, since expressions like `~` or + `*` are escaped, they will end up in the {env}`PATH` verbatim. ''; }; @@ -325,32 +323,32 @@ in type = types.lines; default = ""; internal = true; - description = '' + description = lib.mdDoc '' Extra configuration to add to the - hm-session-vars.sh file. + {file}`hm-session-vars.sh` file. ''; }; home.packages = mkOption { type = types.listOf types.package; default = []; - description = "The set of packages to appear in the user environment."; + description = lib.mdDoc "The set of packages to appear in the user environment."; }; home.extraOutputsToInstall = mkOption { type = types.listOf types.str; default = []; example = [ "doc" "info" "devdoc" ]; - description = '' + description = lib.mdDoc '' List of additional package outputs of the packages - home.packages that should be installed into + {var}`home.packages` that should be installed into the user environment. ''; }; home.path = mkOption { internal = true; - description = "The derivation installing the user packages."; + description = lib.mdDoc "The derivation installing the user packages."; }; home.emptyActivationPath = mkOption { @@ -361,11 +359,11 @@ in false for state version < 22.11, true for state version ≥ 22.11 ''; - description = '' + description = lib.mdDoc '' Whether the activation script should start with an empty - PATH variable. When false then the - user's PATH will be accessible in the script. It is - recommended to keep this at true to avoid + {env}`PATH` variable. When `false` then the + user's {env}`PATH` will be accessible in the script. It is + recommended to keep this at `true` to avoid uncontrolled use of tools found in PATH. ''; }; @@ -381,56 +379,50 @@ in '''; } ''; - description = '' + description = lib.mdDoc '' The activation scripts blocks to run when activating a Home Manager generation. Any entry here should be idempotent, meaning running twice or more times produces the same result as running it once. - - If the script block produces any observable side effect, such as writing or deleting files, then it - must be placed after the special - writeBoundary script block. Prior to the + *must* be placed after the special + `writeBoundary` script block. Prior to the write boundary one can place script blocks that verifies, but does not modify, the state of the system and exits if an unexpected state is found. For example, the - checkLinkTargets script block checks for + `checkLinkTargets` script block checks for collisions between non-managed files and files defined in - . + [](#opt-home.file). - - - A script block should respect the DRY_RUN + A script block should respect the {var}`DRY_RUN` variable, if it is set then the actions taken by the script should be logged to standard out and not actually performed. - The variable DRY_RUN_CMD is set to - echo if dry run is enabled. - - + The variable {var}`DRY_RUN_CMD` is set to + {command}`echo` if dry run is enabled. A script block should also respect the - VERBOSE variable, and if set print + {var}`VERBOSE` variable, and if set print information on standard out that may be useful for debugging any issue that may arise. The variable - VERBOSE_ARG is set to - if verbose output is enabled. + {var}`VERBOSE_ARG` is set to + {option}`--verbose` if verbose output is enabled. ''; }; home.activationPackage = mkOption { internal = true; type = types.package; - description = "The package containing the complete activation script."; + description = lib.mdDoc "The package containing the complete activation script."; }; home.extraActivationPath = mkOption { internal = true; type = types.listOf types.package; default = [ ]; - description = '' - Extra packages to add to PATH within the activation + description = lib.mdDoc '' + Extra packages to add to {env}`PATH` within the activation script. ''; }; @@ -439,7 +431,7 @@ in type = types.lines; default = ""; internal = true; - description = '' + description = lib.mdDoc '' Extra commands to run in the Home Manager generation builder. ''; }; @@ -448,7 +440,7 @@ in type = types.lines; default = ""; internal = true; - description = '' + description = lib.mdDoc '' Extra commands to run in the Home Manager profile builder. ''; }; @@ -456,13 +448,13 @@ in home.enableNixpkgsReleaseCheck = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Determines whether to check for release version mismatch between Home Manager and Nixpkgs. Using mismatched versions is likely to cause errors and unexpected behavior. It is therefore highly recommended to use a release of Home Manager that corresponds with your chosen release of Nixpkgs. - + When this option is enabled and a mismatch is detected then a warning will be printed when the user configuration is being built. ''; diff --git a/modules/i18n/input-method/default.nix b/modules/i18n/input-method/default.nix index 70310e17..d450fcee 100644 --- a/modules/i18n/input-method/default.nix +++ b/modules/i18n/input-method/default.nix @@ -65,7 +65,7 @@ in { internal = true; type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' The input method method package. ''; }; diff --git a/modules/i18n/input-method/fcitx5.nix b/modules/i18n/input-method/fcitx5.nix index 78eb9708..c730a2b3 100644 --- a/modules/i18n/input-method/fcitx5.nix +++ b/modules/i18n/input-method/fcitx5.nix @@ -13,7 +13,7 @@ in { type = with types; listOf package; default = [ ]; example = literalExpression "with pkgs; [ fcitx5-rime ]"; - description = '' + description = lib.mdDoc '' Enabled Fcitx5 addons. ''; }; diff --git a/modules/i18n/input-method/kime.nix b/modules/i18n/input-method/kime.nix index 70f32190..4d47de1f 100644 --- a/modules/i18n/input-method/kime.nix +++ b/modules/i18n/input-method/kime.nix @@ -26,9 +26,9 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' kime configuration. Refer to - + for details on supported values. ''; }; diff --git a/modules/i18n/input-method/uim.nix b/modules/i18n/input-method/uim.nix index e7890352..7c0e1dee 100644 --- a/modules/i18n/input-method/uim.nix +++ b/modules/i18n/input-method/uim.nix @@ -11,7 +11,7 @@ in { type = types.enum [ "gtk" "gtk3" "gtk-systray" "gtk3-systray" "qt4" ]; default = "gtk"; example = "gtk-systray"; - description = '' + description = lib.mdDoc '' Selected UIM toolbar. ''; }; diff --git a/modules/launchd/default.nix b/modules/launchd/default.nix index 3d849bef..68ae554d 100644 --- a/modules/launchd/default.nix +++ b/modules/launchd/default.nix @@ -12,7 +12,7 @@ let launchdConfig = { config, name, ... }: { options = { - enable = mkEnableOption name; + enable = mkEnableOption (lib.mdDoc name); config = mkOption { type = types.submodule (import ./launchd.nix); default = { }; @@ -27,10 +27,8 @@ let ]; } ''; - description = '' - Define a launchd job. See - launchd.plist5 - for details. + description = lib.mdDoc '' + Define a launchd job. See {manpage}`launchd.plist(5)` for details. ''; }; }; @@ -66,7 +64,7 @@ in { type = types.bool; default = isDarwin; defaultText = literalExpression "pkgs.stdenv.hostPlatform.isDarwin"; - description = '' + description = lib.mdDoc '' Whether to enable Home Manager to define per-user daemons by making use of launchd's LaunchAgents. ''; @@ -75,7 +73,7 @@ in { agents = mkOption { type = with types; attrsOf (submodule launchdConfig); default = { }; - description = "Define LaunchAgents."; + description = lib.mdDoc "Define LaunchAgents."; }; }; diff --git a/modules/launchd/launchd.nix b/modules/launchd/launchd.nix index ead9ce76..fc0d505d 100644 --- a/modules/launchd/launchd.nix +++ b/modules/launchd/launchd.nix @@ -33,24 +33,25 @@ with lib; options = { Label = mkOption { type = types.str; - description = "This required key uniquely identifies the job to launchd."; + description = + lib.mdDoc "This required key uniquely identifies the job to launchd."; }; Disabled = mkOption { type = types.nullOr types.bool; default = null; - description = '' - This optional key is used as a hint to launchctl(1) that it should not submit this job to launchd when + description = lib.mdDoc '' + This optional key is used as a hint to `launchctl(1)` that it should not submit this job to launchd when loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration file yourself is not a sufficient test. You should query launchd for the presence of the job using - the launchctl(1) list subcommand or use the ServiceManagement framework's - SMJobCopyDictionary() method. + the `launchctl(1)` list subcommand or use the ServiceManagement framework's + `SMJobCopyDictionary()` method. Note that as of Mac OS X v10.6, this key's value in a configuration file conveys a default value, which - is changed with the [-w] option of the launchctl(1) load and unload subcommands. These subcommands no + is changed with the [-w] option of the `launchctl(1)` load and unload subcommands. These subcommands no longer modify the configuration file, so the value displayed in the configuration file is not necessarily - the value that launchctl(1) will apply. See launchctl(1) for more information. + the value that `launchctl(1)` will apply. See `launchctl(1)` for more information. Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which your job needs to run. The cost to have a @@ -62,7 +63,7 @@ with lib; UserName = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies the user to run the job as. This key is only applicable when launchd is running as root. ''; @@ -71,7 +72,7 @@ with lib; GroupName = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies the group to run the job as. This key is only applicable when launchd is running as root. If UserName is set and GroupName is not, the the group will be set to the default group of the user. @@ -81,7 +82,7 @@ with lib; inetdCompatibility = mkOption { default = null; example = { Wait = true; }; - description = '' + description = lib.mdDoc '' The presence of this key specifies that the daemon expects to be run as if it were launched from inetd. ''; type = types.nullOr (types.submodule { @@ -89,9 +90,9 @@ with lib; Wait = mkOption { type = types.nullOr (types.either types.bool types.str); default = null; - description = '' + description = lib.mdDoc '' This flag corresponds to the "wait" or "nowait" option of inetd. If true, then the listening - socket is passed via the standard in/out/error file descriptors. If false, then accept(2) is + socket is passed via the standard in/out/error file descriptors. If false, then `accept(2)` is called on behalf of the job, and the result is passed via the standard in/out/error descriptors. ''; }; @@ -102,35 +103,35 @@ with lib; LimitLoadToHosts = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = '' + description = lib.mdDoc '' This configuration file only applies to the hosts listed with this key. Note: One should set kern.hostname - in sysctl.conf(5) for this feature to work reliably. + in `sysctl.conf(5)` for this feature to work reliably. ''; }; LimitLoadFromHosts = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = '' + description = lib.mdDoc '' This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname - in sysctl.conf(5) for this feature to work reliably. + in `sysctl.conf(5)` for this feature to work reliably. ''; }; LimitLoadToSessionType = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' This configuration file only applies to sessions of the type specified. This key is used in concert - with the -S flag to launchctl. + with the -S flag to {command}`launchctl`. ''; }; Program = mkOption { type = types.nullOr types.path; default = null; - description = '' - This key maps to the first argument of execvp(3). If this key is missing, then the first element of + description = lib.mdDoc '' + This key maps to the first argument of `execvp(3)`. If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead. This key is required in the absence of the ProgramArguments key. ''; @@ -139,26 +140,26 @@ with lib; ProgramArguments = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = '' - This key maps to the second argument of execvp(3). This key is required in the absence of the Program - key. Please note: many people are confused by this key. Please read execvp(3) very carefully! + description = lib.mdDoc '' + This key maps to the second argument of `execvp(3)`. This key is required in the absence of the Program + key. Please note: many people are confused by this key. Please read `execvp(3)` very carefully! ''; }; EnableGlobbing = mkOption { type = types.nullOr types.bool; default = null; - description = '' - This flag causes launchd to use the glob(3) mechanism to update the program arguments before invocation. + description = lib.mdDoc '' + This flag causes launchd to use the `glob(3)` mechanism to update the program arguments before invocation. ''; }; EnableTransactions = mkOption { type = types.nullOr types.bool; default = null; - description = '' - This flag instructs launchd that the job promises to use vproc_transaction_begin(3) and - vproc_transaction_end(3) to track outstanding transactions that need to be reconciled before the + description = lib.mdDoc '' + This flag instructs launchd that the job promises to use `vproc_transaction_begin(3)` and + `vproc_transaction_end(3)` to track outstanding transactions that need to be reconciled before the process can safely terminate. If no outstanding transactions are in progress, then launchd is free to send the SIGKILL signal. ''; @@ -167,7 +168,7 @@ with lib; OnDemand = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was true. This key has been deprecated and replaced in Mac OS X 10.5 and later with the more powerful KeepAlive option. @@ -181,7 +182,7 @@ with lib; SuccessfulExit = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' If true, the job will be restarted as long as the program exits and with an exit status of zero. If false, the job will be restarted in the inverse condition. This key implies that "RunAtLoad" is set to true, since the job needs to run at least once before we can get an exit status. @@ -191,7 +192,7 @@ with lib; NetworkState = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' If true, the job will be kept alive as long as the network is up, where up is defined as at least one non-loopback interface being up and having IPv4 or IPv6 addresses assigned to them. If false, the job will be kept alive in the inverse condition. @@ -201,7 +202,7 @@ with lib; PathState = mkOption { type = types.nullOr (types.attrsOf types.bool); default = null; - description = '' + description = lib.mdDoc '' Each key in this dictionary is a file-system path. If the value of the key is true, then the job will be kept alive as long as the path exists. If false, the job will be kept alive in the inverse condition. The intent of this feature is that two or more jobs may create semaphores in @@ -212,7 +213,7 @@ with lib; OtherJobEnabled = mkOption { type = types.nullOr (types.attrsOf types.bool); default = null; - description = '' + description = lib.mdDoc '' Each key in this dictionary is the label of another job. If the value of the key is true, then this job is kept alive as long as that other job is enabled. Otherwise, if the value is false, then this job is kept alive as long as the other job is disabled. This feature should not be @@ -223,7 +224,7 @@ with lib; Crashed = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' If true, the the job will be restarted as long as it exited due to a signal which is typically associated with a crash (SIGILL, SIGSEGV, etc.). If false, the job will be restarted in the inverse condition. @@ -238,7 +239,7 @@ with lib; }; })); default = null; - description = '' + description = lib.mdDoc '' This optional key is used to control whether your job is to be kept continuously running or to let demand and conditions control the invocation. The default is false and therefore only demand will start the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictionary @@ -253,7 +254,7 @@ with lib; RunAtLoad = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false. ''; @@ -262,23 +263,23 @@ with lib; RootDirectory = mkOption { type = types.nullOr types.str; default = null; - description = '' - This optional key is used to specify a directory to chroot(2) to before running the job. + description = lib.mdDoc '' + This optional key is used to specify a directory to `chroot(2)` to before running the job. ''; }; WorkingDirectory = mkOption { type = types.nullOr types.str; default = null; - description = '' - This optional key is used to specify a directory to chdir(2) to before running the job. + description = lib.mdDoc '' + This optional key is used to specify a directory to `chdir(2)` to before running the job. ''; }; EnvironmentVariables = mkOption { type = types.nullOr (types.attrsOf types.str); default = null; - description = '' + description = lib.mdDoc '' This optional key is used to specify additional environment variables to be set before running the job. ''; @@ -287,8 +288,8 @@ with lib; Umask = mkOption { type = types.nullOr types.int; default = null; - description = '' - This optional key specifies what value should be passed to umask(2) before running the job. Known bug: + description = lib.mdDoc '' + This optional key specifies what value should be passed to `umask(2)` before running the job. Known bug: Property lists don't support octal, so please convert the value to decimal. ''; }; @@ -296,7 +297,7 @@ with lib; TimeOut = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The recommended idle time out (in seconds) to pass to the job. If no value is specified, a default time out will be supplied by launchd for use by the job at check in time. ''; @@ -305,7 +306,7 @@ with lib; ExitTimeOut = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity. ''; @@ -314,7 +315,7 @@ with lib; ThrottleInterval = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' This key lets one override the default throttling policy imposed on jobs by launchd. The value is in seconds, and by default, jobs will not be spawned more than once every 10 seconds. The principle behind this is that jobs should linger around just in case they are needed again in the near future. @@ -326,8 +327,8 @@ with lib; InitGroups = mkOption { type = types.nullOr types.bool; default = null; - description = '' - This optional key specifies whether initgroups(3) should be called before running the job. The default + description = lib.mdDoc '' + This optional key specifies whether `initgroups(3)` should be called before running the job. The default is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set. ''; }; @@ -335,7 +336,7 @@ with lib; WatchPaths = mkOption { type = types.nullOr (types.listOf types.path); default = null; - description = '' + description = lib.mdDoc '' This optional key causes the job to be started if any one of the listed paths are modified. ''; }; @@ -343,7 +344,7 @@ with lib; QueueDirectories = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = '' + description = lib.mdDoc '' Much like the WatchPaths option, this key will watch the paths for modifications. The difference being that the job will only be started if the path is a directory and the directory is not empty. ''; @@ -352,7 +353,7 @@ with lib; StartOnMount = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This optional key causes the job to be started every time a filesystem is mounted. ''; }; @@ -360,7 +361,7 @@ with lib; StartInterval = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' This optional key causes the job to be started every N seconds. If the system is asleep, the job will be started the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon wake from sleep. @@ -373,9 +374,9 @@ with lib; Hour = 2; Minute = 30; }; - description = '' + description = lib.mdDoc '' This optional key causes the job to be started every calendar interval as specified. Missing arguments - are considered to be wildcard. The semantics are much like crontab(5). Unlike cron which skips job + are considered to be wildcard. The semantics are much like `crontab(5)`. Unlike cron which skips job invocations when the computer is asleep, launchd will start the job the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon wake from sleep. @@ -385,7 +386,7 @@ with lib; Minute = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The minute on which this job will be run. ''; }; @@ -393,7 +394,7 @@ with lib; Hour = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The hour on which this job will be run. ''; }; @@ -401,7 +402,7 @@ with lib; Day = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The day on which this job will be run. ''; }; @@ -409,7 +410,7 @@ with lib; Weekday = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The weekday on which this job will be run (0 and 7 are Sunday). ''; }; @@ -417,7 +418,7 @@ with lib; Month = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The month on which this job will be run. ''; }; @@ -428,32 +429,32 @@ with lib; StandardInPath = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies what file should be used for data being supplied to stdin when using - stdio(3). + `stdio(3)`. ''; }; StandardOutPath = mkOption { type = types.nullOr types.path; default = null; - description = '' - This optional key specifies what file should be used for data being sent to stdout when using stdio(3). + description = lib.mdDoc '' + This optional key specifies what file should be used for data being sent to stdout when using `stdio(3)`. ''; }; StandardErrorPath = mkOption { type = types.nullOr types.path; default = null; - description = '' - This optional key specifies what file should be used for data being sent to stderr when using stdio(3). + description = lib.mdDoc '' + This optional key specifies what file should be used for data being sent to stderr when using `stdio(3)`. ''; }; Debug = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while dealing with this job. ''; @@ -462,7 +463,7 @@ with lib; WaitForDebugger = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies that launchd should instruct the kernel to have the job wait for a debugger to attach before any code in the job is executed. ''; @@ -470,8 +471,8 @@ with lib; SoftResourceLimits = mkOption { default = null; - description = '' - Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following + description = lib.mdDoc '' + Resource limits to be imposed on the job. These adjust variables set with `setrlimit(2)`. The following keys apply: ''; type = types.nullOr (types.submodule { @@ -479,7 +480,7 @@ with lib; Core = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The largest size (in bytes) core file that may be created. ''; }; @@ -487,7 +488,7 @@ with lib; CPU = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum amount of cpu time (in seconds) to be used by each process. ''; }; @@ -495,16 +496,16 @@ with lib; Data = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) of the data segment for a process; this defines how far a program may - extend its break with the sbrk(2) system call. + extend its break with the `sbrk(2)` system call. ''; }; FileSize = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The largest size (in bytes) file that may be created. ''; }; @@ -512,7 +513,7 @@ with lib; MemoryLock = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) which a process may lock into memory using the mlock(2) function. ''; }; @@ -520,27 +521,27 @@ with lib; NumberOfFiles = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum number of open files for this process. Setting this value in a system wide daemon - will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) - value in addition to the setrlimit(2) values. + will set the `sysctl(3)` kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) + value in addition to the `setrlimit(2)` values. ''; }; NumberOfProcesses = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum number of simultaneous processes for this user id. Setting this value in a system - wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid - (HardResourceLimits) value in addition to the setrlimit(2) values. + wide daemon will set the `sysctl(3)` kern.maxproc (SoftResourceLimits) or kern.maxprocperuid + (HardResourceLimits) value in addition to the `setrlimit(2)` values. ''; }; ResidentSetSize = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size. @@ -550,7 +551,7 @@ with lib; Stack = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) of the stack segment for a process; this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system. ''; @@ -562,8 +563,8 @@ with lib; HardResourceLimits = mkOption { default = null; example = { NumberOfFiles = 4096; }; - description = '' - Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following + description = lib.mdDoc '' + Resource limits to be imposed on the job. These adjust variables set with `setrlimit(2)`. The following keys apply: ''; type = types.nullOr (types.submodule { @@ -571,7 +572,7 @@ with lib; Core = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The largest size (in bytes) core file that may be created. ''; }; @@ -579,7 +580,7 @@ with lib; CPU = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum amount of cpu time (in seconds) to be used by each process. ''; }; @@ -587,16 +588,16 @@ with lib; Data = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) of the data segment for a process; this defines how far a program may - extend its break with the sbrk(2) system call. + extend its break with the `sbrk(2)` system call. ''; }; FileSize = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The largest size (in bytes) file that may be created. ''; }; @@ -604,35 +605,35 @@ with lib; MemoryLock = mkOption { type = types.nullOr types.int; default = null; - description = '' - The maximum size (in bytes) which a process may lock into memory using the mlock(2) function. + description = lib.mdDoc '' + The maximum size (in bytes) which a process may lock into memory using the `mlock(2)` function. ''; }; NumberOfFiles = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum number of open files for this process. Setting this value in a system wide daemon - will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) - value in addition to the setrlimit(2) values. + will set the `sysctl(3)` kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) + value in addition to the `setrlimit(2)` values. ''; }; NumberOfProcesses = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum number of simultaneous processes for this user id. Setting this value in a system - wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid - (HardResourceLimits) value in addition to the setrlimit(2) values. + wide daemon will set the `sysctl(3)` kern.maxproc (SoftResourceLimits) or kern.maxprocperuid + (HardResourceLimits) value in addition to the `setrlimit(2)` values. ''; }; ResidentSetSize = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size. @@ -642,7 +643,7 @@ with lib; Stack = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' The maximum size (in bytes) of the stack segment for a process; this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system. ''; @@ -654,7 +655,7 @@ with lib; Nice = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies what nice(3) value should be applied to the daemon. ''; }; @@ -691,7 +692,7 @@ with lib; AbandonProcessGroup = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' When a job dies, launchd kills any remaining processes with the same process group ID as the job. Setting this key to true disables that behavior. ''; @@ -700,7 +701,7 @@ with lib; LowPriorityIO = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O. ''; @@ -709,7 +710,7 @@ with lib; LaunchOnlyOnce = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies whether the job can only be run once and only once. In other words, if the job cannot be safely respawned without a full machine reboot, then set this key to be true. ''; @@ -718,7 +719,7 @@ with lib; MachServices = mkOption { default = null; example = { ResetAtClose = true; }; - description = '' + description = lib.mdDoc '' This optional key is used to specify Mach services to be registered with the Mach bootstrap sub-system. Each key in this dictionary should be the name of service to be advertised. The value of the key must be a boolean and set to true. Alternatively, a dictionary can be used instead of a simple true value. @@ -731,7 +732,7 @@ with lib; ResetAtClose = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' If this boolean is false, the port is recycled, thus leaving clients to remain oblivious to the demand nature of job. If the value is set to true, clients receive port death notifications when the job lets go of the receive right. The port will be recreated atomically with respect to bootstrap_look_up() @@ -744,7 +745,7 @@ with lib; HideUntilCheckIn = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' Reserve the name in the namespace, but cause bootstrap_look_up() to fail until the job has checked in with launchd. ''; @@ -756,7 +757,7 @@ with lib; LaunchEvents = mkOption { type = types.nullOr (types.attrs); default = null; - description = '' + description = lib.mdDoc '' Specifies higher-level event types to be used as launch-on-demand event sources. Each sub-dictionary defines events for a particular event subsystem, such as "com.apple.iokit.matching", which can be used to @@ -780,7 +781,7 @@ with lib; Sockets = mkOption { default = null; - description = '' + description = lib.mdDoc '' This optional key is used to specify launch on demand sockets that can be used to let launchd know when to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in launch(3). The keys of the top level Sockets dictionary can be anything. They are meant for the application @@ -790,14 +791,14 @@ with lib; to be effectively equivalent, even though each file descriptor likely represents a different networking protocol which conforms to the criteria specified in the job configuration file. - The parameters below are used as inputs to call getaddrinfo(3). + The parameters below are used as inputs to call `getaddrinfo(3)`. ''; type = types.nullOr (types.attrsOf (types.submodule { options = { SockType = mkOption { type = types.nullOr (types.enum [ "stream" "dgram" "seqpacket" ]); default = null; - description = '' + description = lib.mdDoc '' This optional key tells launchctl what type of socket to create. The default is "stream" and other valid values for this key are "dgram" and "seqpacket" respectively. ''; @@ -806,8 +807,8 @@ with lib; SockPassive = mkOption { type = types.nullOr types.bool; default = null; - description = '' - This optional key specifies whether listen(2) or connect(2) should be called on the created file + description = lib.mdDoc '' + This optional key specifies whether `listen(2)` or `connect(2)` should be called on the created file descriptor. The default is true ("to listen"). ''; }; @@ -815,23 +816,23 @@ with lib; SockNodeName = mkOption { type = types.nullOr types.str; default = null; - description = '' - This optional key specifies the node to connect(2) or bind(2) to. + description = lib.mdDoc '' + This optional key specifies the node to `connect(2)` or `bind(2)` to. ''; }; SockServiceName = mkOption { type = types.nullOr types.str; default = null; - description = '' - This optional key specifies the service on the node to connect(2) or bind(2) to. + description = lib.mdDoc '' + This optional key specifies the service on the node to `connect(2)` or `bind(2)` to. ''; }; SockFamily = mkOption { type = types.nullOr (types.enum [ "IPv4" "IPv6" ]); default = null; - description = '' + description = lib.mdDoc '' This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created. ''; }; @@ -839,8 +840,8 @@ with lib; SockProtocol = mkOption { type = types.nullOr (types.enum [ "TCP" ]); default = null; - description = '' - This optional key specifies the protocol to be passed to socket(2). The only value understood by + description = lib.mdDoc '' + This optional key specifies the protocol to be passed to `socket(2)`. The only value understood by this key at the moment is "TCP". ''; }; @@ -848,16 +849,16 @@ with lib; SockPathName = mkOption { type = types.nullOr types.path; default = null; - description = '' - This optional key implies SockFamily is set to "Unix". It specifies the path to connect(2) or - bind(2) to. + description = lib.mdDoc '' + This optional key implies SockFamily is set to "Unix". It specifies the path to `connect(2)` or + `bind(2)` to. ''; }; SecureSocketWithKey = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' This optional key is a variant of SockPathName. Instead of binding to a known path, a securely generated socket is created and the path is assigned to the environment variable that is inherited by all jobs spawned by launchd. @@ -867,7 +868,7 @@ with lib; SockPathMode = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' This optional key specifies the mode of the socket. Known bug: Property lists don't support octal, so please convert the value to decimal. ''; @@ -877,18 +878,18 @@ with lib; type = types.nullOr (types.either types.bool (types.listOf types.str)); default = null; - description = '' + description = lib.mdDoc '' This optional key can be used to request that the service be registered with the - mDNSResponder(8). If the value is boolean, the service name is inferred from the SockServiceName. + `mDNSResponder(8)`. If the value is boolean, the service name is inferred from the SockServiceName. ''; }; MulticastGroup = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' This optional key can be used to request that the datagram socket join a multicast group. If the - value is a hostname, then getaddrinfo(3) will be used to join the correct multicast address for a + value is a hostname, then `getaddrinfo(3)` will be used to join the correct multicast address for a given socket family. If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily family also be set, otherwise the results are undefined. ''; diff --git a/modules/lib/file-type.nix b/modules/lib/file-type.nix index ce84209d..537cb557 100644 --- a/modules/lib/file-type.nix +++ b/modules/lib/file-type.nix @@ -19,7 +19,7 @@ in enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether this file should be generated. This option allows specific files to be disabled. ''; @@ -40,18 +40,18 @@ in text = mkOption { default = null; type = types.nullOr types.lines; - description = '' + description = lib.mdDoc '' Text of the file. If this option is null then - + [](#opt-${opt}._name_.source) must be set. ''; }; source = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path of the source file or directory. If - + [](#opt-${opt}._name_.text) is non-null then this option will automatically point to a file containing that text. ''; @@ -60,25 +60,25 @@ in executable = mkOption { type = types.nullOr types.bool; default = null; - description = '' - Set the execute bit. If null, defaults to the mode - of the source file or to false - for files created through the text option. + description = lib.mdDoc '' + Set the execute bit. If `null`, defaults to the mode + of the {var}`source` file or to `false` + for files created through the {var}`text` option. ''; }; recursive = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If the file source is a directory, then this option determines whether the directory should be recursively linked to the target location. This option has no effect if the source is a file. - - If false (the default) then the target + + If `false` (the default) then the target will be a symbolic link to the source directory. If - true then the target will be a + `true` then the target will be a directory structure matching the source's but whose leafs are symbolic links to the files of the source directory. ''; @@ -87,13 +87,13 @@ in onChange = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Shell commands to run when file has changed between generations. The script will be run - after the new files have been linked + *after* the new files have been linked into place. - - Note, this code is always run when recursive is + + Note, this code is always run when `recursive` is enabled. ''; }; @@ -102,7 +102,7 @@ in type = types.bool; default = false; visible = false; - description = '' + description = lib.mdDoc '' Whether the target path should be unconditionally replaced by the managed file source. Warning, this will silently delete the target regardless of whether it is a file or diff --git a/modules/lib/types.nix b/modules/lib/types.nix index 671f3d7e..7c55c349 100644 --- a/modules/lib/types.nix +++ b/modules/lib/types.nix @@ -39,9 +39,9 @@ in rec { type = types.nullOr types.package; default = null; example = literalExpression "pkgs.dejavu_fonts"; - description = '' + description = lib.mdDoc '' Package providing the font. This package will be installed - to your profile. If null then the font + to your profile. If `null` then the font is assumed to already be available in your profile. ''; }; @@ -49,7 +49,7 @@ in rec { name = mkOption { type = types.str; example = "DejaVu Sans"; - description = '' + description = lib.mdDoc '' The family name of the font within the package. ''; }; @@ -58,7 +58,7 @@ in rec { type = types.nullOr types.number; default = null; example = "8"; - description = '' + description = lib.mdDoc '' The size of the font. ''; }; diff --git a/modules/manual.nix b/modules/manual.nix index b7abdcf1..113213a1 100644 --- a/modules/manual.nix +++ b/modules/manual.nix @@ -16,9 +16,9 @@ in { manual.html.enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to install the HTML manual. This also installs the - home-manager-help tool, which opens a local + {command}`home-manager-help` tool, which opens a local copy of the Home Manager manual in the system web browser. ''; }; @@ -27,10 +27,10 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' Whether to install the configuration manual page. The manual can - be reached by man home-configuration.nix. - + be reached by {command}`man home-configuration.nix`. + When looking at the manual page pretend that all references to NixOS stuff are actually references to Home Manager stuff. Thanks! @@ -41,10 +41,10 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to install a JSON formatted list of all Home Manager options. This can be located at - <profile directory>/share/doc/home-manager/options.json, + {file}`/share/doc/home-manager/options.json`, and may be used for navigating definitions, auto-completing, and other miscellaneous tasks. ''; diff --git a/modules/misc/dconf.nix b/modules/misc/dconf.nix index cd66d4d5..c637ea1d 100644 --- a/modules/misc/dconf.nix +++ b/modules/misc/dconf.nix @@ -33,11 +33,11 @@ in { # re-enabled, unclear whether there's actual value in it though. default = !pkgs.stdenv.hostPlatform.isDarwin; visible = false; - description = '' + description = lib.mdDoc '' Whether to enable dconf settings. - + Note, if you use NixOS then you must add - programs.dconf.enable = true + `programs.dconf.enable = true` to your system configuration. Otherwise you will see a systemd error message when your configuration is activated. ''; @@ -57,18 +57,18 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Settings to write to the dconf configuration system. - + Note that the database is strongly-typed so you need to use the same types as described in the GSettings schema. For example, if an option is of type - uint32 (u), you need to wrap the number - using the lib.hm.gvariant.mkUint32 constructor. - Otherwise, since Nix integers are implicitly coerced to int32 - (i), it would get stored in the database as such, and GSettings + `uint32` (`u`), you need to wrap the number + using the `lib.hm.gvariant.mkUint32` constructor. + Otherwise, since Nix integers are implicitly coerced to `int32` + (`i`), it would get stored in the database as such, and GSettings might be confused when loading the setting. - - You might want to use dconf2nix + + You might want to use [dconf2nix](https://github.com/gvolpe/dconf2nix) to convert dconf database dumps into compatible Nix expression. ''; }; diff --git a/modules/misc/editorconfig.nix b/modules/misc/editorconfig.nix index 2c9764af..289ba7f0 100644 --- a/modules/misc/editorconfig.nix +++ b/modules/misc/editorconfig.nix @@ -12,16 +12,16 @@ in { meta.maintainers = with maintainers; [ loicreynier ]; options.editorconfig = { - enable = mkEnableOption "EditorConfig home configuration file"; + enable = mkEnableOption (lib.mdDoc "EditorConfig home configuration file"); settings = mkOption { type = iniFormat.type; default = { }; - description = '' - Configuration written to $HOME/.editorconfig. - root = true is automatically added to the file, + description = lib.mdDoc '' + Configuration written to {file}`$HOME/.editorconfig`. + `root = true` is automatically added to the file, it must not be added here. - See for documentation. + See for documentation. ''; example = literalExpression '' { diff --git a/modules/misc/fontconfig.nix b/modules/misc/fontconfig.nix index 74415c2f..5a861f96 100644 --- a/modules/misc/fontconfig.nix +++ b/modules/misc/fontconfig.nix @@ -24,12 +24,12 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable fontconfig configuration. This will, for example, allow fontconfig to discover fonts and configurations installed through - home.packages and - nix-env. + {var}`home.packages` and + {command}`nix-env`. ''; }; }; diff --git a/modules/misc/gtk.nix b/modules/misc/gtk.nix index 035cafae..85a23123 100644 --- a/modules/misc/gtk.nix +++ b/modules/misc/gtk.nix @@ -31,9 +31,9 @@ let type = types.nullOr types.package; default = null; example = literalExpression "pkgs.gnome.gnome-themes-extra"; - description = '' + description = lib.mdDoc '' Package providing the theme. This package will be installed - to your profile. If null then the theme + to your profile. If `null` then the theme is assumed to already be available in your profile. ''; }; @@ -41,7 +41,7 @@ let name = mkOption { type = types.str; example = "Adwaita"; - description = "The name of the theme within the package."; + description = lib.mdDoc "The name of the theme within the package."; }; }; }; @@ -52,9 +52,9 @@ let type = types.nullOr types.package; default = null; example = literalExpression "pkgs.gnome.adwaita-icon-theme"; - description = '' + description = lib.mdDoc '' Package providing the icon theme. This package will be installed - to your profile. If null then the theme + to your profile. If `null` then the theme is assumed to already be available in your profile. ''; }; @@ -62,7 +62,8 @@ let name = mkOption { type = types.str; example = "Adwaita"; - description = "The name of the icon theme within the package."; + description = + lib.mdDoc "The name of the icon theme within the package."; }; }; }; @@ -73,9 +74,9 @@ let type = types.nullOr types.package; default = null; example = literalExpression "pkgs.vanilla-dmz"; - description = '' + description = lib.mdDoc '' Package providing the cursor theme. This package will be installed - to your profile. If null then the theme + to your profile. If `null` then the theme is assumed to already be available in your profile. ''; }; @@ -83,14 +84,15 @@ let name = mkOption { type = types.str; example = "Vanilla-DMZ"; - description = "The name of the cursor theme within the package."; + description = + lib.mdDoc "The name of the cursor theme within the package."; }; size = mkOption { type = types.nullOr types.int; default = null; example = 16; - description = '' + description = lib.mdDoc '' The size of the cursor. ''; }; @@ -108,12 +110,12 @@ in { options = { gtk = { - enable = mkEnableOption "GTK 2/3 configuration"; + enable = mkEnableOption (lib.mdDoc "GTK 2/3 configuration"); font = mkOption { type = types.nullOr hm.types.fontType; default = null; - description = '' + description = lib.mdDoc '' The font to use in GTK+ 2/3 applications. ''; }; @@ -121,19 +123,19 @@ in { cursorTheme = mkOption { type = types.nullOr cursorThemeType; default = null; - description = "The cursor theme to use."; + description = lib.mdDoc "The cursor theme to use."; }; iconTheme = mkOption { type = types.nullOr iconThemeType; default = null; - description = "The icon theme to use."; + description = lib.mdDoc "The icon theme to use."; }; theme = mkOption { type = types.nullOr themeType; default = null; - description = "The GTK+2/3 theme to use."; + description = lib.mdDoc "The GTK+2/3 theme to use."; }; gtk2 = { @@ -141,9 +143,9 @@ in { type = types.lines; default = ""; example = "gtk-can-change-accels = 1"; - description = '' + description = lib.mdDoc '' Extra configuration lines to add verbatim to - ~/.gtkrc-2.0. + {file}`~/.gtkrc-2.0`. ''; }; @@ -154,7 +156,7 @@ in { literalExpression ''"''${config.home.homeDirectory}/.gtkrc-2.0"''; example = literalExpression ''"''${config.xdg.configHome}/gtk-2.0/gtkrc"''; - description = '' + description = lib.mdDoc '' The location to put the GTK configuration file. ''; }; @@ -165,7 +167,8 @@ in { type = types.listOf types.str; default = [ ]; example = [ "file:///home/jane/Documents" ]; - description = "Bookmarks in the sidebar of the GTK file browser"; + description = + lib.mdDoc "Bookmarks in the sidebar of the GTK file browser"; }; extraConfig = mkOption { @@ -175,18 +178,18 @@ in { gtk-cursor-blink = false; gtk-recent-files-limit = 20; }; - description = '' + description = lib.mdDoc '' Extra configuration options to add to - $XDG_CONFIG_HOME/gtk-3.0/settings.ini. + {file}`$XDG_CONFIG_HOME/gtk-3.0/settings.ini`. ''; }; extraCss = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration lines to add verbatim to - $XDG_CONFIG_HOME/gtk-3.0/gtk.css. + {file}`$XDG_CONFIG_HOME/gtk-3.0/gtk.css`. ''; }; }; @@ -199,18 +202,18 @@ in { gtk-cursor-blink = false; gtk-recent-files-limit = 20; }; - description = '' + description = lib.mdDoc '' Extra configuration options to add to - $XDG_CONFIG_HOME/gtk-4.0/settings.ini. + {file}`$XDG_CONFIG_HOME/gtk-4.0/settings.ini`. ''; }; extraCss = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration lines to add verbatim to - $XDG_CONFIG_HOME/gtk-4.0/gtk.css. + {file}`$XDG_CONFIG_HOME/gtk-4.0/gtk.css`. ''; }; }; diff --git a/modules/misc/lib.nix b/modules/misc/lib.nix index 13c00dc5..5125091c 100644 --- a/modules/misc/lib.nix +++ b/modules/misc/lib.nix @@ -5,7 +5,7 @@ lib = lib.mkOption { type = lib.types.attrsOf lib.types.attrs; default = { }; - description = '' + description = lib.mdDoc '' This option allows modules to define helper functions, constants, etc. ''; diff --git a/modules/misc/news.nix b/modules/misc/news.nix index 7228f18d..6dadb50b 100644 --- a/modules/misc/news.nix +++ b/modules/misc/news.nix @@ -13,7 +13,7 @@ let id = mkOption { internal = true; type = types.str; - description = '' + description = lib.mdDoc '' A unique entry identifier. By default it is a base16 formatted hash of the entry message. ''; @@ -23,7 +23,7 @@ let internal = true; type = types.str; example = "2017-07-10T21:55:04+00:00"; - description = '' + description = lib.mdDoc '' News entry time stamp in ISO-8601 format. Must be in UTC (ending in '+00:00'). ''; @@ -32,13 +32,13 @@ let condition = mkOption { internal = true; default = true; - description = "Whether the news entry should be active."; + description = lib.mdDoc "Whether the news entry should be active."; }; message = mkOption { internal = true; type = types.str; - description = "The news entry content."; + description = lib.mdDoc "The news entry content."; }; }; @@ -83,7 +83,7 @@ in internal = true; type = types.listOf entryModule; default = [ ]; - description = "News entries."; + description = lib.mdDoc "News entries."; }; }; }; diff --git a/modules/misc/nix.nix b/modules/misc/nix.nix index 1b5511b4..9bb518f9 100644 --- a/modules/misc/nix.nix +++ b/modules/misc/nix.nix @@ -82,9 +82,9 @@ let in { options.nix = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' the Nix configuration module - '' // { + '') // { default = true; visible = false; }; @@ -93,7 +93,7 @@ in { type = types.nullOr types.package; default = null; example = literalExpression "pkgs.nix"; - description = '' + description = lib.mdDoc '' The Nix package that the configuration should be generated for. ''; }; @@ -110,7 +110,7 @@ in { type = "indirect"; id = "nixpkgs"; }; - description = "The flake reference to be rewritten."; + description = lib.mdDoc "The flake reference to be rewritten."; }; to = mkOption { type = inputAttrs; @@ -119,24 +119,24 @@ in { owner = "my-org"; repo = "my-nixpkgs"; }; - description = - "The flake reference to which is to be rewritten."; + description = lib.mdDoc + "The flake reference to which {option}`from>` is to be rewritten."; }; flake = mkOption { type = types.nullOr types.attrs; default = null; example = literalExpression "nixpkgs"; - description = '' - The flake input to which is to be rewritten. + description = lib.mdDoc '' + The flake input to which {option}`from>` is to be rewritten. ''; }; exact = mkOption { type = types.bool; default = true; - description = '' - Whether the reference needs to match exactly. If set, - a reference like nixpkgs does not - match with a reference like nixpkgs/nixos-20.03. + description = lib.mdDoc '' + Whether the {option}`from` reference needs to match exactly. If set, + a {option}`from` reference like `nixpkgs` does not + match with a reference like `nixpkgs/nixos-20.03`. ''; }; }; @@ -154,7 +154,7 @@ in { }; })); default = { }; - description = '' + description = lib.mdDoc '' User level flake registry. ''; }; @@ -163,13 +163,13 @@ in { type = types.int; default = 2; internal = true; - description = "The flake registry format version."; + description = lib.mdDoc "The flake registry format version."; }; checkConfig = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' If enabled (the default), checks for data type mismatches and that Nix can parse the generated nix.conf. ''; @@ -182,8 +182,7 @@ in { keep-outputs = true keep-derivations = true ''; - description = - "Additional text appended to nix.conf."; + description = lib.mdDoc "Additional text appended to {file}`nix.conf`."; }; settings = mkOption { diff --git a/modules/misc/nixpkgs.nix b/modules/misc/nixpkgs.nix index 42f6724c..b1767e55 100644 --- a/modules/misc/nixpkgs.nix +++ b/modules/misc/nixpkgs.nix @@ -48,29 +48,25 @@ in { default = null; example = { allowBroken = true; }; type = types.nullOr 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. - - - If null, then configuration is taken from + If `null`, then configuration is taken from the fallback location, for example, - ~/.config/nixpkgs/config.nix. - - + {file}`~/.config/nixpkgs/config.nix`. Note, this option will not apply outside your Home Manager configuration like when installing manually through - nix-env. If you want to apply it both + {command}`nix-env`. If you want to apply it both inside and outside Home Manager you can put it in a separate file and include something like - + ```nix nixpkgs.config = import ./nixpkgs-config.nix; xdg.configFile."nixpkgs/config.nix".source = ./nixpkgs-config.nix; - + ``` in your Home Manager configuration. ''; @@ -90,25 +86,21 @@ in { ] ''; type = types.nullOr (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. This is a function that takes as - an argument the original Nixpkgs. The + an argument the *original* Nixpkgs. The first argument should be used for finding dependencies, and the second should be used for overriding recipes. - - - If null, then the overlays are taken from + If `null`, then the overlays are taken from the fallback location, for example, - ~/.config/nixpkgs/overlays. + {file}`~/.config/nixpkgs/overlays`. - - - Like nixpkgs.config this option only + Like {var}`nixpkgs.config` this option only applies within the Home Manager configuration. See - nixpkgs.config for a suggested setup that + {var}`nixpkgs.config` for a suggested setup that works both internally and externally. ''; }; @@ -117,7 +109,7 @@ in { type = types.str; example = "i686-linux"; internal = true; - description = '' + description = lib.mdDoc '' Specifies the Nix platform type for which the user environment should be built. If unset, it defaults to the platform type of your host system. Specifying this option is useful when doing diff --git a/modules/misc/numlock.nix b/modules/misc/numlock.nix index 88032417..f2539262 100644 --- a/modules/misc/numlock.nix +++ b/modules/misc/numlock.nix @@ -9,7 +9,9 @@ let in { meta.maintainers = [ maintainers.evanjs ]; - options = { xsession.numlock.enable = mkEnableOption "Num Lock"; }; + options = { + xsession.numlock.enable = mkEnableOption (lib.mdDoc "Num Lock"); + }; config = mkIf cfg.enable { assertions = [ diff --git a/modules/misc/pam.nix b/modules/misc/pam.nix index cf3321ff..7e56274b 100644 --- a/modules/misc/pam.nix +++ b/modules/misc/pam.nix @@ -14,14 +14,11 @@ in { default = { }; type = types.attrs; example = { EDITOR = "vim"; }; - description = '' + description = lib.mdDoc '' Environment variables that will be set for the PAM session. The variable values must be as described in - - pam_env.conf - 5 - . - + {manpage}`pam_env.conf(5)`. + Note, this option will become deprecated in the future and its use is therefore discouraged. ''; @@ -37,9 +34,9 @@ in { }; in listOf yubiKeyId; default = [ ]; - description = '' + description = lib.mdDoc '' List of authorized YubiKey token IDs. Refer to - + for details on how to obtain the token ID of a YubiKey. ''; }; @@ -47,9 +44,9 @@ in { path = mkOption { type = types.str; default = ".yubico/authorized_yubikeys"; - description = '' + description = lib.mdDoc '' File path to write the authorized YubiKeys, - relative to HOME. + relative to {env}`HOME`. ''; }; }; diff --git a/modules/misc/qt.nix b/modules/misc/qt.nix index d90f8493..3c0fe122 100644 --- a/modules/misc/qt.nix +++ b/modules/misc/qt.nix @@ -41,7 +41,7 @@ in { options = { qt = { - enable = mkEnableOption "Qt 4, 5 and 6 configuration"; + enable = mkEnableOption (lib.mdDoc "Qt 4, 5 and 6 configuration"); platformTheme = mkOption { type = types.nullOr (types.enum [ "gtk" "gnome" "qtct" "kde" ]); @@ -119,9 +119,9 @@ in { type = with types; nullOr (either package (listOf package)); default = null; example = literalExpression "pkgs.adwaita-qt"; - description = '' + description = lib.mdDoc '' Theme package to be used in Qt5/Qt6 applications. - Auto-detected from if possible. + Auto-detected from {option}`qt.style.name` if possible. ''; }; }; diff --git a/modules/misc/specialisation.nix b/modules/misc/specialisation.nix index 69c3f617..a16ded2f 100644 --- a/modules/misc/specialisation.nix +++ b/modules/misc/specialisation.nix @@ -27,7 +27,7 @@ with lib; in extended.type; default = { }; visible = "shallow"; - description = '' + description = lib.mdDoc '' Arbitrary Home Manager configuration settings. ''; }; diff --git a/modules/misc/submodule-support.nix b/modules/misc/submodule-support.nix index ff80291c..b685f8dd 100644 --- a/modules/misc/submodule-support.nix +++ b/modules/misc/submodule-support.nix @@ -10,7 +10,7 @@ with lib; type = types.bool; default = false; internal = true; - description = '' + description = lib.mdDoc '' Whether the Home Manager module system is used as a submodule in, for example, NixOS or nix-darwin. ''; @@ -20,12 +20,12 @@ with lib; type = types.bool; default = false; internal = true; - description = '' - Whether the packages of are + description = lib.mdDoc '' + Whether the packages of {option}`home.packages` are installed separately from the Home Manager activation script. In NixOS, for example, this may be accomplished by installing the packages through - . + {option}`users.users.‹name?›.packages`. ''; }; }; diff --git a/modules/misc/tmpfiles.nix b/modules/misc/tmpfiles.nix index 24884302..735a7912 100644 --- a/modules/misc/tmpfiles.nix +++ b/modules/misc/tmpfiles.nix @@ -13,13 +13,10 @@ in { type = types.listOf types.str; default = [ ]; example = [ "L /home/user/Documents - - - - /mnt/data/Documents" ]; - description = '' + description = lib.mdDoc '' Rules for creating and cleaning up temporary files automatically. See - - tmpfiles.d - 5 - + {manpage}`tmpfiles.d(5)` for the exact format. ''; }; diff --git a/modules/misc/version.nix b/modules/misc/version.nix index 548268ed..d6170eae 100644 --- a/modules/misc/version.nix +++ b/modules/misc/version.nix @@ -21,13 +21,13 @@ in { "23.05" "23.11" ]; - description = '' + description = lib.mdDoc '' It is occasionally necessary for Home Manager to change configuration defaults in a way that is incompatible with stateful data. This could, for example, include switching the default data format or location of a file. - - The state version indicates which default + + The *state version* indicates which default settings are in effect and will therefore help avoid breaking program configurations. Switching to a higher state version typically requires performing some manual steps, such as data @@ -46,7 +46,7 @@ in { optionalString (revision != null) "+${substring 0 8 revision}"; in "${release}${suffix}"; example = "22.11+213a0629"; - description = "The full Home Manager version."; + description = lib.mdDoc "The full Home Manager version."; }; release = mkOption { @@ -55,7 +55,7 @@ in { type = types.str; default = releaseInfo.release; example = "22.11"; - description = "The Home Manager release."; + description = lib.mdDoc "The Home Manager release."; }; isReleaseBranch = mkOption { @@ -63,7 +63,7 @@ in { readOnly = true; type = types.bool; default = releaseInfo.isReleaseBranch; - description = '' + description = lib.mdDoc '' Whether the Home Manager version is from a versioned release branch. ''; @@ -74,7 +74,7 @@ in { type = types.nullOr types.str; default = let gitRepo = "${toString ./../..}/.git"; in if pathIsGitRepo gitRepo then commitIdFromGitRepo gitRepo else null; - description = '' + description = lib.mdDoc '' The Git revision from which this Home Manager configuration was built. ''; }; diff --git a/modules/misc/xdg-desktop-entries.nix b/modules/misc/xdg-desktop-entries.nix index 6fbcd79a..6c01dad2 100644 --- a/modules/misc/xdg-desktop-entries.nix +++ b/modules/misc/xdg-desktop-entries.nix @@ -26,63 +26,65 @@ let # https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys type = mkOption { - description = "The type of the desktop entry."; + description = lib.mdDoc "The type of the desktop entry."; default = "Application"; type = types.enum [ "Application" "Link" "Directory" ]; }; exec = mkOption { - description = "Program to execute, possibly with arguments."; + description = lib.mdDoc "Program to execute, possibly with arguments."; type = types.nullOr types.str; default = null; }; icon = mkOption { - description = "Icon to display in file manager, menus, etc."; + description = lib.mdDoc "Icon to display in file manager, menus, etc."; type = with types; nullOr (either str path); default = null; }; comment = mkOption { - description = "Tooltip for the entry."; + description = lib.mdDoc "Tooltip for the entry."; type = types.nullOr types.str; default = null; }; terminal = mkOption { - description = "Whether the program runs in a terminal window."; + description = + lib.mdDoc "Whether the program runs in a terminal window."; type = types.bool; default = false; }; name = mkOption { - description = "Specific name of the application."; + description = lib.mdDoc "Specific name of the application."; type = types.str; }; genericName = mkOption { - description = "Generic name of the application."; + description = lib.mdDoc "Generic name of the application."; type = types.nullOr types.str; default = null; }; mimeType = mkOption { - description = "The MIME type(s) supported by this application."; + description = + lib.mdDoc "The MIME type(s) supported by this application."; type = types.nullOr (types.listOf types.str); default = null; }; categories = mkOption { description = - "Categories in which the entry should be shown in a menu."; + lib.mdDoc "Categories in which the entry should be shown in a menu."; type = types.nullOr (types.listOf types.str); default = null; }; startupNotify = mkOption { - description = '' + description = lib.mdDoc '' If true, it is KNOWN that the application will send a "remove" - message when started with the DESKTOP_STARTUP_ID + message when started with the `DESKTOP_STARTUP_ID` environment variable set. If false, it is KNOWN that the application does not work with startup notification at all.''; type = types.nullOr types.bool; @@ -90,7 +92,7 @@ let }; noDisplay = mkOption { - description = '' + description = lib.mdDoc '' Means "this application exists, but don't display it in the menus". This can be useful to e.g. associate this application with MIME types. ''; @@ -99,7 +101,7 @@ let }; prefersNonDefaultGPU = mkOption { - description = '' + description = lib.mdDoc '' If true, the application prefers to be run on a more powerful discrete GPU if available. ''; type = types.nullOr types.bool; @@ -108,8 +110,8 @@ let settings = mkOption { type = types.attrsOf types.string; - description = '' - Extra key-value pairs to add to the [Desktop Entry] section. + description = lib.mdDoc '' + Extra key-value pairs to add to the `[Desktop Entry]` section. This may override other values. ''; default = { }; @@ -127,17 +129,19 @@ let type = types.str; default = name; defaultText = literalExpression ""; - description = "Name of the action."; + description = lib.mdDoc "Name of the action."; }; options.exec = mkOption { type = types.nullOr types.str; - description = "Program to execute, possibly with arguments."; + description = + lib.mdDoc "Program to execute, possibly with arguments."; default = null; }; options.icon = mkOption { type = with types; nullOr (either str path); default = null; - description = "Icon to display in file manager, menus, etc."; + description = + lib.mdDoc "Icon to display in file manager, menus, etc."; }; })); default = { }; @@ -149,7 +153,7 @@ let }; } ''; - description = + description = lib.mdDoc "The set of actions made available to application launchers."; }; @@ -180,12 +184,12 @@ in { meta.maintainers = [ hm.maintainers.cwyc ]; options.xdg.desktopEntries = mkOption { - description = '' + description = lib.mdDoc '' Desktop Entries allow applications to be shown in your desktop environment's app launcher. You can define entries for programs without entries or override existing entries. - See for more information on options. + See for more information on options. ''; default = { }; type = types.attrsOf (types.submodule desktopEntry); diff --git a/modules/misc/xdg-mime-apps.nix b/modules/misc/xdg-mime-apps.nix index 2093caa2..1b21f9b9 100644 --- a/modules/misc/xdg-mime-apps.nix +++ b/modules/misc/xdg-mime-apps.nix @@ -16,10 +16,9 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' - Whether to manage $XDG_CONFIG_HOME/mimeapps.list. - - + description = lib.mdDoc '' + Whether to manage {file}`$XDG_CONFIG_HOME/mimeapps.list`. + The generated file is read-only. ''; }; @@ -36,7 +35,7 @@ in { "mimetype2" = "foo4.desktop"; } ''; - description = '' + description = lib.mdDoc '' Defines additional associations of applications with mimetypes, as if the .desktop file was listing this mimetype in the first place. @@ -47,9 +46,9 @@ in { type = types.attrsOf strListOrSingleton; default = { }; example = { "mimetype1" = "foo5.desktop"; }; - description = '' + description = lib.mdDoc '' Removes associations of applications with mimetypes, as if the - .desktop file was not listing this + .desktop file was *not* listing this mimetype in the first place. ''; }; @@ -62,7 +61,7 @@ in { "mimetype1" = [ "default1.desktop" "default2.desktop" ]; } ''; - description = '' + description = lib.mdDoc '' The default application to be used for a given mimetype. This is, for instance, the one that will be started when double-clicking on a file in a file manager. If the diff --git a/modules/misc/xdg-mime.nix b/modules/misc/xdg-mime.nix index c9c7658d..ef36e709 100644 --- a/modules/misc/xdg-mime.nix +++ b/modules/misc/xdg-mime.nix @@ -13,13 +13,13 @@ in { default = pkgs.stdenv.hostPlatform.isLinux; defaultText = literalExpression "true if host platform is Linux, false otherwise"; - description = '' + description = lib.mdDoc '' Whether to install programs and files to support the XDG Shared MIME-info specification and XDG MIME Applications specification at - + and - , + , respectively. ''; }; diff --git a/modules/misc/xdg-system-dirs.nix b/modules/misc/xdg-system-dirs.nix index 989131c5..5d6c78bf 100644 --- a/modules/misc/xdg-system-dirs.nix +++ b/modules/misc/xdg-system-dirs.nix @@ -18,8 +18,8 @@ in { type = types.listOf types.str; default = [ ]; example = literalExpression ''[ "/etc/xdg" ]''; - description = '' - Directory names to add to XDG_CONFIG_DIRS + description = lib.mdDoc '' + Directory names to add to {env}`XDG_CONFIG_DIRS` in the user session. ''; }; @@ -28,8 +28,8 @@ in { type = types.listOf types.str; default = [ ]; example = literalExpression ''[ "/usr/share" "/usr/local/share" ]''; - description = '' - Directory names to add to XDG_DATA_DIRS + description = lib.mdDoc '' + Directory names to add to {env}`XDG_DATA_DIRS` in the user session. ''; }; diff --git a/modules/misc/xdg-user-dirs.nix b/modules/misc/xdg-user-dirs.nix index 2ea07709..f435bdaf 100644 --- a/modules/misc/xdg-user-dirs.nix +++ b/modules/misc/xdg-user-dirs.nix @@ -21,10 +21,9 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' - Whether to manage $XDG_CONFIG_HOME/user-dirs.dirs. - - + description = lib.mdDoc '' + Whether to manage {file}`$XDG_CONFIG_HOME/user-dirs.dirs`. + The generated file is read-only. ''; }; @@ -37,7 +36,7 @@ in { default = "${config.home.homeDirectory}/Desktop"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Desktop"''; - description = "The Desktop directory."; + description = lib.mdDoc "The Desktop directory."; }; documents = mkOption { @@ -45,7 +44,7 @@ in { default = "${config.home.homeDirectory}/Documents"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Documents"''; - description = "The Documents directory."; + description = lib.mdDoc "The Documents directory."; }; download = mkOption { @@ -53,7 +52,7 @@ in { default = "${config.home.homeDirectory}/Downloads"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Downloads"''; - description = "The Downloads directory."; + description = lib.mdDoc "The Downloads directory."; }; music = mkOption { @@ -61,7 +60,7 @@ in { default = "${config.home.homeDirectory}/Music"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Music"''; - description = "The Music directory."; + description = lib.mdDoc "The Music directory."; }; pictures = mkOption { @@ -69,7 +68,7 @@ in { default = "${config.home.homeDirectory}/Pictures"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Pictures"''; - description = "The Pictures directory."; + description = lib.mdDoc "The Pictures directory."; }; publicShare = mkOption { @@ -77,7 +76,7 @@ in { default = "${config.home.homeDirectory}/Public"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Public"''; - description = "The Public share directory."; + description = lib.mdDoc "The Public share directory."; }; templates = mkOption { @@ -85,7 +84,7 @@ in { default = "${config.home.homeDirectory}/Templates"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Templates"''; - description = "The Templates directory."; + description = lib.mdDoc "The Templates directory."; }; videos = mkOption { @@ -93,7 +92,7 @@ in { default = "${config.home.homeDirectory}/Videos"; defaultText = literalExpression ''"''${config.home.homeDirectory}/Videos"''; - description = "The Videos directory."; + description = lib.mdDoc "The Videos directory."; }; extraConfig = mkOption { @@ -105,11 +104,11 @@ in { XDG_MISC_DIR = "''${config.home.homeDirectory}/Misc"; } ''; - description = "Other user directories."; + description = lib.mdDoc "Other user directories."; }; - createDirectories = - mkEnableOption "automatic creation of the XDG user directories"; + createDirectories = mkEnableOption + (lib.mdDoc "automatic creation of the XDG user directories"); }; config = let diff --git a/modules/misc/xdg.nix b/modules/misc/xdg.nix index 23cbe72a..d2ffc36f 100644 --- a/modules/misc/xdg.nix +++ b/modules/misc/xdg.nix @@ -22,13 +22,13 @@ let in { options.xdg = { - enable = mkEnableOption "management of XDG base directories"; + enable = mkEnableOption (lib.mdDoc "management of XDG base directories"); cacheHome = mkOption { type = types.path; defaultText = "~/.cache"; apply = toString; - description = '' + description = lib.mdDoc '' Absolute path to directory holding application caches. ''; }; @@ -36,7 +36,7 @@ in { configFile = mkOption { type = fileType "xdg.configFile" "{var}`xdg.configHome`" cfg.configHome; default = { }; - description = '' + description = lib.mdDoc '' Attribute set of files to link into the user's XDG configuration home. ''; @@ -46,7 +46,7 @@ in { type = types.path; defaultText = "~/.config"; apply = toString; - description = '' + description = lib.mdDoc '' Absolute path to directory holding application configurations. ''; }; @@ -55,7 +55,7 @@ in { type = fileType "xdg.dataFile" "xdg.dataHome" cfg.dataHome; default = { }; - description = '' + description = lib.mdDoc '' Attribute set of files to link into the user's XDG data home. ''; @@ -65,7 +65,7 @@ in { type = types.path; defaultText = "~/.local/share"; apply = toString; - description = '' + description = lib.mdDoc '' Absolute path to directory holding application data. ''; }; @@ -74,7 +74,7 @@ in { type = types.path; defaultText = "~/.local/state"; apply = toString; - description = '' + description = lib.mdDoc '' Absolute path to directory holding application states. ''; }; diff --git a/modules/misc/xfconf.nix b/modules/misc/xfconf.nix index 2eda5efd..c82f05e9 100644 --- a/modules/misc/xfconf.nix +++ b/modules/misc/xfconf.nix @@ -10,7 +10,7 @@ let options = { type = mkOption { type = types.enum [ "int" "uint" "uint64" ]; - description = '' + description = lib.mdDoc '' To distinguish between int, uint and uint64 in xfconf, you can specify the type in xfconf with this submodule. For other types, you don't need to use this submodule, @@ -19,7 +19,7 @@ let }; value = mkOption { type = types.int; - description = "The value in xfconf."; + description = lib.mdDoc "The value in xfconf."; }; }; }; @@ -63,11 +63,11 @@ in { type = types.bool; default = true; visible = false; - description = '' + description = lib.mdDoc '' Whether to enable Xfconf settings. - + Note, if you use NixOS then you must add - programs.xfconf.enable = true + `programs.xfconf.enable = true` to your system configuration. Otherwise you will see a systemd error message when your configuration is activated. ''; @@ -93,7 +93,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Settings to write to the Xfconf configuration system. ''; }; diff --git a/modules/programs/abook.nix b/modules/programs/abook.nix index bdbf7e87..8276cd36 100644 --- a/modules/programs/abook.nix +++ b/modules/programs/abook.nix @@ -8,7 +8,7 @@ let in { options.programs.abook = { - enable = mkEnableOption "Abook"; + enable = mkEnableOption (lib.mdDoc "Abook"); extraConfig = mkOption { type = types.lines; @@ -18,10 +18,10 @@ in { view CONTACT = name, email set autosave=true ''; - description = '' - Extra lines added to $HOME/.config/abook/abookrc. + description = lib.mdDoc '' + Extra lines added to {file}`$HOME/.config/abook/abookrc`. Available configuration options are described in the abook repository: - . + . ''; }; }; diff --git a/modules/programs/aerc-accounts.nix b/modules/programs/aerc-accounts.nix index 81a985f1..40bd18a1 100644 --- a/modules/programs/aerc-accounts.nix +++ b/modules/programs/aerc-accounts.nix @@ -39,10 +39,10 @@ let }); default = null; example = { token_endpoint = ""; }; - description = '' + description = lib.mdDoc '' Sets the oauth2 params if authentication mechanism oauthbearer or xoauth2 is used. - See aerc-imap5. + See {manpage}`aerc-imap(5)`. ''; }; @@ -50,16 +50,16 @@ in { type = mkOption { type = types.attrsOf (types.submodule { options.aerc = { - enable = mkEnableOption "aerc"; + enable = mkEnableOption (lib.mdDoc "aerc"); extraAccounts = mkOption { type = confSection; default = { }; example = literalExpression ''{ source = "maildir://~/Maildir/example"; }''; - description = '' + description = lib.mdDoc '' Extra config added to the configuration section for this account in - $HOME/.config/aerc/accounts.conf. - See aerc-accounts5. + {file}`$HOME/.config/aerc/accounts.conf`. + See {manpage}`aerc-accounts(5)`. ''; }; @@ -68,10 +68,10 @@ in { default = { }; example = literalExpression ''{ messages = { d = ":move ''${folder.trash}"; }; }''; - description = '' + description = lib.mdDoc '' Extra bindings specific to this account, added to - $HOME/.config/aerc/binds.conf. - See aerc-binds5. + {file}`$HOME/.config/aerc/binds.conf`. + See {manpage}`aerc-binds(5)`. ''; }; @@ -79,12 +79,12 @@ in { type = confSections; default = { }; example = literalExpression "{ ui = { sidebar-width = 25; }; }"; - description = '' - Config specific to this account, added to $HOME/.config/aerc/aerc.conf. + description = lib.mdDoc '' + Config specific to this account, added to {file}`$HOME/.config/aerc/aerc.conf`. Aerc only supports per-account UI configuration. - For other sections of $HOME/.config/aerc/aerc.conf, - use programs.aerc.extraConfig. - See aerc-config5. + For other sections of {file}`$HOME/.config/aerc/aerc.conf`, + use `programs.aerc.extraConfig`. + See {manpage}`aerc-config(5)`. ''; }; @@ -92,10 +92,10 @@ in { type = with types; nullOr (enum [ "oauthbearer" "xoauth2" ]); default = null; example = "auth"; - description = '' + description = lib.mdDoc '' Sets the authentication mechanism if imap is used as the incoming method. - See aerc-imap5. + See {manpage}`aerc-imap(5)`. ''; }; @@ -106,10 +106,10 @@ in { nullOr (enum [ "none" "plain" "login" "oauthbearer" "xoauth2" ]); default = "plain"; example = "auth"; - description = '' + description = lib.mdDoc '' Sets the authentication mechanism if smtp is used as the outgoing method. - See aerc-smtp5. + See {manpage}`aerc-smtp(5)`. ''; }; diff --git a/modules/programs/aerc.nix b/modules/programs/aerc.nix index 9f3cf76e..81110a14 100644 --- a/modules/programs/aerc.nix +++ b/modules/programs/aerc.nix @@ -31,7 +31,7 @@ in { options.programs.aerc = { - enable = mkEnableOption "aerc"; + enable = mkEnableOption (lib.mdDoc "aerc"); package = mkPackageOptionMD pkgs "aerc" { }; diff --git a/modules/programs/afew.nix b/modules/programs/afew.nix index 6c480f03..9c604889 100644 --- a/modules/programs/afew.nix +++ b/modules/programs/afew.nix @@ -8,7 +8,8 @@ let in { options.programs.afew = { - enable = mkEnableOption "the afew initial tagging script for Notmuch"; + enable = + mkEnableOption (lib.mdDoc "the afew initial tagging script for Notmuch"); extraConfig = mkOption { type = types.lines; @@ -29,10 +30,10 @@ in { [InboxFilter] ''; - description = '' + description = lib.mdDoc '' Extra lines added to afew configuration file. Available configuration options are described in the afew manual: - . + . ''; }; }; diff --git a/modules/programs/alacritty.nix b/modules/programs/alacritty.nix index eaf30414..f52f63a6 100644 --- a/modules/programs/alacritty.nix +++ b/modules/programs/alacritty.nix @@ -8,13 +8,13 @@ let in { options = { programs.alacritty = { - enable = mkEnableOption "Alacritty"; + enable = mkEnableOption (lib.mdDoc "Alacritty"); package = mkOption { type = types.package; default = pkgs.alacritty; defaultText = literalExpression "pkgs.alacritty"; - description = "The Alacritty package to install."; + description = lib.mdDoc "The Alacritty package to install."; }; settings = mkOption { @@ -35,10 +35,10 @@ in { ]; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/alacritty/alacritty.yml. See - + {file}`$XDG_CONFIG_HOME/alacritty/alacritty.yml`. See + for the default configuration. ''; }; diff --git a/modules/programs/alot-accounts.nix b/modules/programs/alot-accounts.nix index 9dee3c83..6cfce4a8 100644 --- a/modules/programs/alot-accounts.nix +++ b/modules/programs/alot-accounts.nix @@ -7,10 +7,10 @@ with lib; options.alot = { sendMailCommand = mkOption { type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Command to send a mail. If msmtp is enabled for the account, then this is set to - msmtpq --read-envelope-from --read-recipients. + {command}`msmtpq --read-envelope-from --read-recipients`. ''; }; @@ -33,9 +33,9 @@ with lib; ignorecase = "True"; } ''; - description = '' + description = lib.mdDoc '' Contact completion configuration as expected per alot. - See alot's wiki for + See [alot's wiki](http://alot.readthedocs.io/en/latest/configuration/contacts_completion.html) for explanation about possible values. ''; }; @@ -43,7 +43,7 @@ with lib; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra settings to add to this Alot account configuration. ''; }; diff --git a/modules/programs/alot.nix b/modules/programs/alot.nix index 22a29be1..c86f7222 100644 --- a/modules/programs/alot.nix +++ b/modules/programs/alot.nix @@ -25,20 +25,20 @@ let options = { translated = mkOption { type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Fixed string representation for this tag. The tag can be hidden from view, if the key translated is set to - "", the empty string. + `""`, the empty string. ''; }; translation = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' A pair of strings that define a regular substitution to compute the string representation on the fly using - re.sub. + `re.sub`. ''; }; @@ -46,16 +46,16 @@ let type = types.nullOr types.str; default = null; example = "'','', 'white','light red', 'white','#d66'"; - description = '' + description = lib.mdDoc '' How to display the tag when unfocused. - See . + See . ''; }; focus = mkOption { type = types.nullOr types.str; default = null; - description = "How to display the tag when focused."; + description = lib.mdDoc "How to display the tag when focused."; }; }; }; @@ -125,7 +125,7 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to enable the Alot mail user agent. Alot uses the Notmuch email system and will therefore be automatically enabled for each email account that is managed by Notmuch. @@ -135,7 +135,7 @@ in { hooks = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Content of the hooks file. ''; }; @@ -146,42 +146,42 @@ in { global = mkOption { type = types.attrsOf types.str; default = { }; - description = "Global keybindings."; + description = lib.mdDoc "Global keybindings."; }; bufferlist = mkOption { type = types.attrsOf types.str; default = { }; - description = "Bufferlist mode keybindings."; + description = lib.mdDoc "Bufferlist mode keybindings."; }; search = mkOption { type = types.attrsOf types.str; default = { }; - description = "Search mode keybindings."; + description = lib.mdDoc "Search mode keybindings."; }; envelope = mkOption { type = types.attrsOf types.str; default = { }; - description = "Envelope mode keybindings."; + description = lib.mdDoc "Envelope mode keybindings."; }; taglist = mkOption { type = types.attrsOf types.str; default = { }; - description = "Taglist mode keybindings."; + description = lib.mdDoc "Taglist mode keybindings."; }; thread = mkOption { type = types.attrsOf types.str; default = { }; - description = "Thread mode keybindings."; + description = lib.mdDoc "Thread mode keybindings."; }; }; }; default = { }; - description = '' + description = lib.mdDoc '' Keybindings. ''; }; @@ -189,7 +189,7 @@ in { tags = mkOption { type = types.attrsOf tagSubmodule; default = { }; - description = "How to display the tags."; + description = lib.mdDoc "How to display the tags."; }; settings = mkOption { @@ -209,7 +209,7 @@ in { thread_indent_replies = 2; } ''; - description = '' + description = lib.mdDoc '' Configuration options added to alot configuration file. ''; }; @@ -217,7 +217,7 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra lines added to alot configuration file. ''; }; diff --git a/modules/programs/antidote.nix b/modules/programs/antidote.nix index e90c9903..e5c769cf 100644 --- a/modules/programs/antidote.nix +++ b/modules/programs/antidote.nix @@ -19,16 +19,16 @@ in { meta.maintainers = [ maintainers.hitsmaxft ]; options.programs.zsh.antidote = { - enable = mkEnableOption "antidote - a zsh plugin manager"; + enable = mkEnableOption (lib.mdDoc "antidote - a zsh plugin manager"); plugins = mkOption { type = types.listOf types.str; default = [ ]; example = [ "zsh-users/zsh-autosuggestions" ]; - description = "List of antidote plugins."; + description = lib.mdDoc "List of antidote plugins."; }; - useFriendlyNames = mkEnableOption "friendly names"; + useFriendlyNames = mkEnableOption (lib.mdDoc "friendly names"); package = mkPackageOptionMD pkgs "antidote" { }; }; diff --git a/modules/programs/aria2.nix b/modules/programs/aria2.nix index 25727cea..c26e09db 100644 --- a/modules/programs/aria2.nix +++ b/modules/programs/aria2.nix @@ -17,18 +17,15 @@ in { meta.maintainers = [ hm.maintainers.justinlovinger ]; options.programs.aria2 = { - enable = mkEnableOption "aria2"; + enable = mkEnableOption (lib.mdDoc "aria2"); settings = mkOption { type = with types; attrsOf (oneOf [ bool float int str ]); default = { }; - description = '' - Options to add to aria2.conf file. + description = lib.mdDoc '' + Options to add to {file}`aria2.conf` file. See - - aria2c - 1 - + {manpage}`aria2c(1)` for options. ''; example = literalExpression '' @@ -45,8 +42,8 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra lines added to aria2.conf file. + description = lib.mdDoc '' + Extra lines added to {file}`aria2.conf` file. ''; }; }; diff --git a/modules/programs/astroid-accounts.nix b/modules/programs/astroid-accounts.nix index fb803867..49711c51 100644 --- a/modules/programs/astroid-accounts.nix +++ b/modules/programs/astroid-accounts.nix @@ -4,14 +4,14 @@ with lib; { options.astroid = { - enable = mkEnableOption "Astroid"; + enable = mkEnableOption (lib.mdDoc "Astroid"); sendMailCommand = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Command to send a mail. If msmtp is enabled for the account, then this is set to - msmtpq --read-envelope-from --read-recipients. + {command}`msmtpq --read-envelope-from --read-recipients`. ''; }; @@ -19,7 +19,7 @@ with lib; type = types.attrsOf types.anything; default = { }; example = { select_query = ""; }; - description = '' + description = lib.mdDoc '' Extra settings to add to this astroid account configuration. ''; }; diff --git a/modules/programs/astroid.nix b/modules/programs/astroid.nix index f40797dd..7bc0e252 100644 --- a/modules/programs/astroid.nix +++ b/modules/programs/astroid.nix @@ -55,13 +55,13 @@ let in { options = { programs.astroid = { - enable = mkEnableOption "Astroid"; + enable = mkEnableOption (lib.mdDoc "Astroid"); pollScript = mkOption { type = types.str; default = ""; example = "mbsync gmail"; - description = '' + description = lib.mdDoc '' Script to run to fetch/update mails. ''; }; @@ -104,7 +104,7 @@ in { poll.interval = 0; } ''; - description = '' + description = lib.mdDoc '' JSON config that will override the default Astroid configuration. ''; }; diff --git a/modules/programs/atuin.nix b/modules/programs/atuin.nix index 68f23ce8..2f84e616 100644 --- a/modules/programs/atuin.nix +++ b/modules/programs/atuin.nix @@ -12,31 +12,31 @@ in { meta.maintainers = [ maintainers.hawkw ]; options.programs.atuin = { - enable = mkEnableOption "atuin"; + enable = mkEnableOption (lib.mdDoc "atuin"); package = mkOption { type = types.package; default = pkgs.atuin; defaultText = literalExpression "pkgs.atuin"; - description = "The package to use for atuin."; + description = lib.mdDoc "The package to use for atuin."; }; enableBashIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Atuin's Bash integration. This will bind - ctrl-r to open the Atuin history. + `ctrl-r` to open the Atuin history. ''; }; enableZshIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Atuin's Zsh integration. - - If enabled, this will bind ctrl-r and the up-arrow + + If enabled, this will bind `ctrl-r` and the up-arrow key to open the Atuin history. ''; }; @@ -44,9 +44,9 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Atuin's Fish integration. - + If enabled, this will bind the up-arrow key to open the Atuin history. ''; }; @@ -55,7 +55,7 @@ in { default = [ ]; type = types.listOf types.str; example = [ "--disable-up-arrow" "--disable-ctrl-r" ]; - description = '' + description = lib.mdDoc '' Flags to append to the shell hook. ''; }; @@ -78,11 +78,11 @@ in { search_mode = "prefix"; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/atuin/config.toml. - - See for the full list + {file}`$XDG_CONFIG_HOME/atuin/config.toml`. + + See for the full list of options. ''; }; @@ -90,7 +90,7 @@ in { enableNushellIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Nushell integration. ''; }; diff --git a/modules/programs/autojump.nix b/modules/programs/autojump.nix index e8bf6b43..74e06763 100644 --- a/modules/programs/autojump.nix +++ b/modules/programs/autojump.nix @@ -11,12 +11,12 @@ in { meta.maintainers = [ maintainers.evanjs ]; options.programs.autojump = { - enable = mkEnableOption "autojump"; + enable = mkEnableOption (lib.mdDoc "autojump"); enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -24,7 +24,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -32,7 +32,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/autorandr.nix b/modules/programs/autorandr.nix index 47c810f5..8dfa16ce 100644 --- a/modules/programs/autorandr.nix +++ b/modules/programs/autorandr.nix @@ -26,22 +26,22 @@ let options = { fingerprint = mkOption { type = types.attrsOf types.str; - description = '' + description = lib.mdDoc '' Output name to EDID mapping. - Use autorandr --fingerprint to get current setup values. + Use `autorandr --fingerprint` to get current setup values. ''; default = { }; }; config = mkOption { type = types.attrsOf configModule; - description = "Per output profile configuration."; + description = lib.mdDoc "Per output profile configuration."; default = { }; }; hooks = mkOption { type = profileHooksModule; - description = "Profile hook scripts."; + description = lib.mdDoc "Profile hook scripts."; default = { }; }; }; @@ -51,54 +51,54 @@ let options = { enable = mkOption { type = types.bool; - description = "Whether to enable the output."; + description = lib.mdDoc "Whether to enable the output."; default = true; }; crtc = mkOption { type = types.nullOr types.ints.unsigned; - description = "Output video display controller."; + description = lib.mdDoc "Output video display controller."; default = null; example = 0; }; primary = mkOption { type = types.bool; - description = "Whether output should be marked as primary"; + description = lib.mdDoc "Whether output should be marked as primary"; default = false; }; position = mkOption { type = types.str; - description = "Output position"; + description = lib.mdDoc "Output position"; default = ""; example = "5760x0"; }; mode = mkOption { type = types.str; - description = "Output resolution."; + description = lib.mdDoc "Output resolution."; default = ""; example = "3840x2160"; }; rate = mkOption { type = types.str; - description = "Output framerate."; + description = lib.mdDoc "Output framerate."; default = ""; example = "60.00"; }; gamma = mkOption { type = types.str; - description = "Output gamma configuration."; + description = lib.mdDoc "Output gamma configuration."; default = ""; example = "1.0:0.909:0.833"; }; rotate = mkOption { type = types.nullOr (types.enum [ "normal" "left" "right" "inverted" ]); - description = "Output rotate configuration."; + description = lib.mdDoc "Output rotate configuration."; default = null; example = "left"; }; @@ -113,19 +113,16 @@ let [ 0.0 0.0 1.0 ] ] ''; - description = '' + description = lib.mdDoc '' Refer to - - xrandr - 1 - + {manpage}`xrandr(1)` for the documentation of the transform matrix. ''; }; dpi = mkOption { type = types.nullOr types.ints.positive; - description = "Output DPI configuration."; + description = lib.mdDoc "Output DPI configuration."; default = null; example = 96; }; @@ -135,36 +132,33 @@ let options = { method = mkOption { type = types.enum [ "factor" "pixel" ]; - description = "Output scaling method."; + description = lib.mdDoc "Output scaling method."; default = "factor"; example = "pixel"; }; x = mkOption { type = types.either types.float types.ints.positive; - description = "Horizontal scaling factor/pixels."; + description = lib.mdDoc "Horizontal scaling factor/pixels."; }; y = mkOption { type = types.either types.float types.ints.positive; - description = "Vertical scaling factor/pixels."; + description = lib.mdDoc "Vertical scaling factor/pixels."; }; }; }); - description = '' + description = lib.mdDoc '' Output scale configuration. - + Either configure by pixels or a scaling factor. When using pixel method the - - xrandr - 1 - + {manpage}`xrandr(1)` option - --scale-from + `--scale-from` will be used; when using factor method the option - --scale + `--scale` will be used. - + This option is a shortcut version of the transform option and they are mutually exclusive. ''; @@ -179,7 +173,8 @@ let filter = mkOption { type = types.nullOr (types.enum [ "bilinear" "nearest" ]); - description = "Interpolation method to be used for scaling the output."; + description = + lib.mdDoc "Interpolation method to be used for scaling the output."; default = null; example = "nearest"; }; @@ -192,19 +187,19 @@ let options = { postswitch = mkOption { type = types.attrsOf hookType; - description = "Postswitch hook executed after mode switch."; + description = lib.mdDoc "Postswitch hook executed after mode switch."; default = { }; }; preswitch = mkOption { type = types.attrsOf hookType; - description = "Preswitch hook executed before mode switch."; + description = lib.mdDoc "Preswitch hook executed before mode switch."; default = { }; }; predetect = mkOption { type = types.attrsOf hookType; - description = '' + description = lib.mdDoc '' Predetect hook executed before autorandr attempts to run xrandr. ''; default = { }; @@ -216,19 +211,19 @@ let options = { postswitch = mkOption { type = hookType; - description = "Postswitch hook executed after mode switch."; + description = lib.mdDoc "Postswitch hook executed after mode switch."; default = ""; }; preswitch = mkOption { type = hookType; - description = "Preswitch hook executed before mode switch."; + description = lib.mdDoc "Preswitch hook executed before mode switch."; default = ""; }; predetect = mkOption { type = hookType; - description = '' + description = lib.mdDoc '' Predetect hook executed before autorandr attempts to run xrandr. ''; default = ""; @@ -282,11 +277,11 @@ let in { options = { programs.autorandr = { - enable = mkEnableOption "Autorandr"; + enable = mkEnableOption (lib.mdDoc "Autorandr"); hooks = mkOption { type = globalHooksModule; - description = "Global hook scripts"; + description = lib.mdDoc "Global hook scripts"; default = { }; example = literalExpression '' { @@ -318,7 +313,7 @@ in { profiles = mkOption { type = types.attrsOf profileModule; - description = "Autorandr profiles specification."; + description = lib.mdDoc "Autorandr profiles specification."; default = { }; example = literalExpression '' { diff --git a/modules/programs/bash.nix b/modules/programs/bash.nix index e3c937df..614c4a69 100644 --- a/modules/programs/bash.nix +++ b/modules/programs/bash.nix @@ -27,25 +27,23 @@ in { options = { programs.bash = { - enable = mkEnableOption "GNU Bourne-Again SHell"; + enable = mkEnableOption (lib.mdDoc "GNU Bourne-Again SHell"); enableCompletion = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Bash completion for all interactive Bash shells. - - Note, if you use NixOS or nix-darwin and do not have Bash completion enabled in the system configuration, then make sure to add - + ```nix environment.pathsToLink = [ "/share/bash-completion" ]; - + ``` to your system configuration to get completion for system packages. - Note, the legacy /etc/bash_completion.d path is + Note, the legacy {file}`/etc/bash_completion.d` path is not supported by Home Manager. ''; }; @@ -53,33 +51,34 @@ in { historySize = mkOption { type = types.int; default = 10000; - description = "Number of history lines to keep in memory."; + description = lib.mdDoc "Number of history lines to keep in memory."; }; historyFile = mkOption { type = types.nullOr types.str; default = null; - description = "Location of the bash history file."; + description = lib.mdDoc "Location of the bash history file."; }; historyFileSize = mkOption { type = types.int; default = 100000; - description = "Number of history lines to keep on file."; + description = lib.mdDoc "Number of history lines to keep on file."; }; historyControl = mkOption { type = types.listOf (types.enum [ "erasedups" "ignoredups" "ignorespace" ]); default = [ ]; - description = "Controlling how commands are saved on the history list."; + description = + lib.mdDoc "Controlling how commands are saved on the history list."; }; historyIgnore = mkOption { type = types.listOf types.str; default = [ ]; example = [ "ls" "cd" "exit" ]; - description = + description = lib.mdDoc "List of commands that should not be saved to the history list."; }; @@ -101,9 +100,9 @@ in { "checkjobs" ]; example = [ "extglob" "-cdspell" ]; - description = '' + description = lib.mdDoc '' Shell options to set. Prefix an option with - "-" to unset. + "`-`" to unset. ''; }; @@ -111,7 +110,7 @@ in { default = { }; type = types.attrs; example = { MAILCHECK = 30; }; - description = '' + description = lib.mdDoc '' Environment variables that will be set for the Bash session. ''; }; @@ -125,7 +124,7 @@ in { ".." = "cd .."; } ''; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. ''; @@ -134,7 +133,7 @@ in { profileExtra = mkOption { default = ""; type = types.lines; - description = '' + description = lib.mdDoc '' Extra commands that should be run when initializing a login shell. ''; @@ -143,7 +142,7 @@ in { initExtra = mkOption { default = ""; type = types.lines; - description = '' + description = lib.mdDoc '' Extra commands that should be run when initializing an interactive shell. ''; @@ -152,8 +151,8 @@ in { bashrcExtra = mkOption { default = ""; type = types.lines; - description = '' - Extra commands that should be placed in ~/.bashrc. + description = lib.mdDoc '' + Extra commands that should be placed in {file}`~/.bashrc`. Note that these commands will be run even in non-interactive shells. ''; }; @@ -161,7 +160,7 @@ in { logoutExtra = mkOption { default = ""; type = types.lines; - description = '' + description = lib.mdDoc '' Extra commands that should be run when logging out of an interactive shell. ''; diff --git a/modules/programs/bashmount.nix b/modules/programs/bashmount.nix index 38d57456..4a418b42 100644 --- a/modules/programs/bashmount.nix +++ b/modules/programs/bashmount.nix @@ -10,15 +10,15 @@ in { meta.maintainers = [ maintainers.AndersonTorres ]; options.programs.bashmount = { - enable = mkEnableOption "bashmount"; + enable = mkEnableOption (lib.mdDoc "bashmount"); extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/bashmount/config. Look at - + {file}`$XDG_CONFIG_HOME/bashmount/config`. Look at + for explanation about possible values. ''; }; diff --git a/modules/programs/bat.nix b/modules/programs/bat.nix index 6890a28a..5fa605e7 100644 --- a/modules/programs/bat.nix +++ b/modules/programs/bat.nix @@ -17,7 +17,7 @@ in { meta.maintainers = [ ]; options.programs.bat = { - enable = mkEnableOption "bat, a cat clone with wings"; + enable = mkEnableOption (lib.mdDoc "bat, a cat clone with wings"); config = mkOption { type = with types; attrsOf (either str (listOf str)); @@ -27,7 +27,7 @@ in { pager = "less -FR"; map-syntax = [ "*.jenkinsfile:Groovy" "*.props:Java Properties" ]; }; - description = '' + description = lib.mdDoc '' Bat configuration. ''; }; @@ -37,7 +37,7 @@ in { default = [ ]; example = literalExpression "with pkgs.bat-extras; [ batdiff batman batgrep batwatch ];"; - description = '' + description = lib.mdDoc '' Additional bat packages to install. ''; }; @@ -55,7 +55,7 @@ in { } + "/Dracula.tmTheme"); } ''; - description = '' + description = lib.mdDoc '' Additional themes to provide. ''; }; diff --git a/modules/programs/beets.nix b/modules/programs/beets.nix index 6cadcf9c..20e785ca 100644 --- a/modules/programs/beets.nix +++ b/modules/programs/beets.nix @@ -20,11 +20,11 @@ in { else cfg.settings != { }; defaultText = "false"; - description = '' + description = lib.mdDoc '' Whether to enable the beets music library manager. This - defaults to false for state + defaults to `false` for state version ≥ 19.03. For earlier versions beets is enabled if - is non-empty. + {option}`programs.beets.settings` is non-empty. ''; }; @@ -34,8 +34,8 @@ in { defaultText = literalExpression "pkgs.beets"; example = literalExpression "(pkgs.beets.override { enableCheck = true; })"; - description = '' - The beets package to use. + description = lib.mdDoc '' + The `beets` package to use. Can be used to specify extensions. ''; }; @@ -43,22 +43,22 @@ in { settings = mkOption { type = yamlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/beets/config.yaml + {file}`$XDG_CONFIG_HOME/beets/config.yaml` ''; }; mpdIntegration = { - enableStats = mkEnableOption "mpdstats plugin and service"; + enableStats = mkEnableOption (lib.mdDoc "mpdstats plugin and service"); - enableUpdate = mkEnableOption "mpdupdate plugin"; + enableUpdate = mkEnableOption (lib.mdDoc "mpdupdate plugin"); host = mkOption { type = types.str; default = "localhost"; example = "10.0.0.42"; - description = "The host that mpdstats will connect to."; + description = lib.mdDoc "The host that mpdstats will connect to."; }; port = mkOption { @@ -66,7 +66,7 @@ in { default = config.services.mpd.network.port; defaultText = literalExpression "config.services.mpd.network.port"; example = 6601; - description = "The port that mpdstats will connect to."; + description = lib.mdDoc "The port that mpdstats will connect to."; }; }; }; diff --git a/modules/programs/borgmatic.nix b/modules/programs/borgmatic.nix index 29983363..a25ebd53 100644 --- a/modules/programs/borgmatic.nix +++ b/modules/programs/borgmatic.nix @@ -16,7 +16,7 @@ let mkRetentionOption = frequency: mkNullableOption { type = types.int; - description = + description = lib.mdDoc "Number of ${frequency} archives to keep. Use -1 for no limit."; example = 3; }; @@ -24,20 +24,20 @@ let extraConfigOption = mkOption { type = yamlFormat.type; default = { }; - description = "Extra settings."; + description = lib.mdDoc "Extra settings."; }; consistencyCheckModule = types.submodule { options = { name = mkOption { type = types.enum [ "repository" "archives" "data" "extract" ]; - description = "Name of consistency check to run."; + description = lib.mdDoc "Name of consistency check to run."; example = "repository"; }; frequency = mkNullableOption { type = types.strMatching "([[:digit:]]+ .*)|always"; - description = "Frequency of this type of check"; + description = lib.mdDoc "Frequency of this type of check"; example = "2 weeks"; }; }; @@ -51,20 +51,20 @@ let location = { sourceDirectories = mkOption { type = types.listOf types.str; - description = "Directories to backup."; + description = lib.mdDoc "Directories to backup."; example = literalExpression "[config.home.homeDirectory]"; }; repositories = mkOption { type = types.listOf types.str; - description = "Paths to repositories."; + description = lib.mdDoc "Paths to repositories."; example = literalExpression ''["ssh://myuser@myrepo.myserver.com/./repo"]''; }; excludeHomeManagerSymlinks = mkOption { type = types.bool; - description = '' + description = lib.mdDoc '' Whether to exclude Home Manager generated symbolic links from the backups. This facilitates restoring the whole home directory when the Nix store doesn't contain the latest @@ -80,7 +80,8 @@ let storage = { encryptionPasscommand = mkNullableOption { type = types.str; - description = "Command writing the passphrase to standard output."; + description = + lib.mdDoc "Command writing the passphrase to standard output."; example = literalExpression ''"''${pkgs.password-store}/bin/pass borg-repo"''; }; @@ -90,7 +91,8 @@ let retention = { keepWithin = mkNullableOption { type = types.strMatching "[[:digit:]]+[Hdwmy]"; - description = "Keep all archives within this time interval."; + description = + lib.mdDoc "Keep all archives within this time interval."; example = "2d"; }; @@ -109,7 +111,7 @@ let checks = mkOption { type = types.listOf consistencyCheckModule; default = [ ]; - description = "Consistency checks to run"; + description = lib.mdDoc "Consistency checks to run"; example = literalExpression '' [ { @@ -180,13 +182,13 @@ in { options = { programs.borgmatic = { - enable = mkEnableOption "Borgmatic"; + enable = mkEnableOption (lib.mdDoc "Borgmatic"); package = mkPackageOptionMD pkgs "borgmatic" { }; backups = mkOption { type = types.attrsOf configModule; - description = '' + description = lib.mdDoc '' Borgmatic allows for several named backup configurations, each with its own source directories and repositories. ''; diff --git a/modules/programs/bottom.nix b/modules/programs/bottom.nix index cb09256c..b2c0875f 100644 --- a/modules/programs/bottom.nix +++ b/modules/programs/bottom.nix @@ -11,25 +11,25 @@ let in { options = { programs.bottom = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' bottom, a cross-platform graphical process/system monitor with a - customizable interface''; + customizable interface''); package = mkOption { type = types.package; default = pkgs.bottom; defaultText = literalExpression "pkgs.bottom"; - description = "Package providing bottom."; + description = lib.mdDoc "Package providing {command}`bottom`."; }; settings = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/bottom/bottom.toml. - - See + {file}`$XDG_CONFIG_HOME/bottom/bottom.toml`. + + See for the default configuration. ''; example = literalExpression '' diff --git a/modules/programs/boxxy.nix b/modules/programs/boxxy.nix index b6d68f54..9dbfc60b 100644 --- a/modules/programs/boxxy.nix +++ b/modules/programs/boxxy.nix @@ -12,7 +12,7 @@ let options = { name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Unique identifier of the boxxy rule. This can be any single-line string. ''; }; @@ -21,7 +21,7 @@ let type = types.str; default = ""; example = "~/.ssh"; - description = '' + description = lib.mdDoc '' What directory/file to redirect. ''; }; @@ -30,7 +30,7 @@ let type = types.str; default = ""; example = literalExpression ''"''${config.xdg.configHome}/ssh"''; - description = '' + description = lib.mdDoc '' Where that file/directory should be rewritten to. ''; }; @@ -38,7 +38,7 @@ let mode = mkOption { type = types.enum [ "file" "directory" ]; default = "directory"; - description = '' + description = lib.mdDoc '' Does the current path redirect a file or a directory? ''; }; @@ -52,7 +52,7 @@ let "/usr/bin/sh" ] ''; - description = '' + description = lib.mdDoc '' Apply redirection ONLY to specified executable names. ''; }; @@ -61,7 +61,7 @@ let type = types.listOf types.str; default = [ ]; example = [ "/home/example/Projects/my-project" ]; - description = '' + description = lib.mdDoc '' Apply redirection ONLY when in a certain directory. ''; }; @@ -74,7 +74,7 @@ let MY_ENV_VAR = "my_env_var_value"; } ''; - description = '' + description = lib.mdDoc '' Give certain environment variables for said match. ''; }; @@ -82,14 +82,15 @@ let }; in { options.programs.boxxy = { - enable = mkEnableOption "boxxy: Boxes in badly behaving applications"; + enable = + mkEnableOption (lib.mdDoc "boxxy: Boxes in badly behaving applications"); package = mkPackageOptionMD pkgs "boxxy" { }; rules = mkOption { type = types.listOf boxxyRulesOpts; default = [ ]; - description = "List of boxxy rules"; + description = lib.mdDoc "List of boxxy rules"; }; }; diff --git a/modules/programs/broot.nix b/modules/programs/broot.nix index 361dcfc6..d9b11f9e 100644 --- a/modules/programs/broot.nix +++ b/modules/programs/broot.nix @@ -12,7 +12,7 @@ let freeformType = tomlFormat.type; options = { - modal = mkEnableOption "modal (vim) mode"; + modal = mkEnableOption (lib.mdDoc "modal (vim) mode"); verbs = mkOption { type = with types; listOf (attrsOf (either bool str)); @@ -149,12 +149,13 @@ in { ]; options.programs.broot = { - enable = mkEnableOption "Broot, a better way to navigate directories"; + enable = + mkEnableOption (lib.mdDoc "Broot, a better way to navigate directories"); enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -162,7 +163,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -170,7 +171,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; @@ -179,13 +180,13 @@ in { type = types.package; default = pkgs.broot; defaultText = literalExpression "pkgs.broot"; - description = "Package providing broot"; + description = lib.mdDoc "Package providing broot"; }; settings = mkOption { type = types.submodule settingsModule; default = { }; - description = "Verbatim config entries"; + description = lib.mdDoc "Verbatim config entries"; }; }; diff --git a/modules/programs/browserpass.nix b/modules/programs/browserpass.nix index 8faf5315..c0cc223c 100644 --- a/modules/programs/browserpass.nix +++ b/modules/programs/browserpass.nix @@ -8,13 +8,14 @@ let in { options = { programs.browserpass = { - enable = mkEnableOption "the browserpass extension host application"; + enable = + mkEnableOption (lib.mdDoc "the browserpass extension host application"); browsers = mkOption { type = types.listOf (types.enum browsers); default = browsers; example = [ "firefox" ]; - description = "Which browsers to install browserpass for"; + description = lib.mdDoc "Which browsers to install browserpass for"; }; }; }; diff --git a/modules/programs/btop.nix b/modules/programs/btop.nix index 2bee9125..45e54f65 100644 --- a/modules/programs/btop.nix +++ b/modules/programs/btop.nix @@ -28,7 +28,7 @@ in { meta.maintainers = [ hm.maintainers.GaetanLepage ]; options.programs.btop = { - enable = mkEnableOption "btop"; + enable = mkEnableOption (lib.mdDoc "btop"); package = mkPackageOptionMD pkgs "btop" { }; @@ -39,9 +39,9 @@ in { color_theme = "Default"; theme_background = false; }; - description = '' - Options to add to btop.conf file. - See + description = lib.mdDoc '' + Options to add to {file}`btop.conf` file. + See for options. ''; }; @@ -49,8 +49,8 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra lines added to the btop.conf file. + description = lib.mdDoc '' + Extra lines added to the {file}`btop.conf` file. ''; }; }; diff --git a/modules/programs/chromium.nix b/modules/programs/chromium.nix index c97fd059..a663b93c 100644 --- a/modules/programs/chromium.nix +++ b/modules/programs/chromium.nix @@ -23,7 +23,7 @@ let type = types.bool; default = false; example = true; - description = "Whether to enable ${name}."; + description = lib.mdDoc "Whether to enable ${name}."; }; package = mkOption { @@ -31,7 +31,7 @@ let type = types.package; default = defaultPkg; defaultText = literalExpression "pkgs.${browser}"; - description = "The ${name} package to use."; + description = lib.mdDoc "The ${name} package to use."; }; commandLineArgs = mkOption { @@ -39,14 +39,14 @@ let type = types.listOf types.str; default = [ ]; example = [ "--enable-logging=stderr" "--ignore-gpu-blocklist" ]; - description = '' + description = lib.mdDoc '' List of command-line arguments to be passed to ${name}. - + For a list of common switches, see - Chrome switches. - + [Chrome switches](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/chrome/common/chrome_switches.cc). + To search switches for other components, see - Chromium codesearch. + [Chromium codesearch](https://source.chromium.org/search?q=file:switches.cc&ss=chromium%2Fchromium%2Fsrc). ''; }; } // optionalAttrs (!isProprietaryChrome) { @@ -60,7 +60,7 @@ let options = { id = mkOption { type = strMatching "[a-zA-Z]{32}"; - description = '' + description = lib.mdDoc '' The extension's ID from the Chrome Web Store url or the unpacked crx. ''; default = ""; @@ -68,7 +68,7 @@ let updateUrl = mkOption { type = str; - description = '' + description = lib.mdDoc '' URL of the extension's update manifest XML file. Linux only. ''; default = "https://clients2.google.com/service/update2/crx"; @@ -78,7 +78,7 @@ let crxPath = mkOption { type = nullOr path; - description = '' + description = lib.mdDoc '' Path to the extension's crx file. Linux only. ''; default = null; @@ -87,7 +87,7 @@ let version = mkOption { type = nullOr str; - description = '' + description = lib.mdDoc '' The extension's version, required for local installation. Linux only. ''; default = null; @@ -111,16 +111,16 @@ let } ] ''; - description = '' + description = lib.mdDoc '' List of ${name} extensions to install. To find the extension ID, check its URL on the - Chrome Web Store. - + [Chrome Web Store](https://chrome.google.com/webstore/category/extensions). + To install extensions outside of the Chrome Web Store set - updateUrl or crxPath and - version as explained in the - Chrome - documentation. + `updateUrl` or `crxPath` and + `version` as explained in the + [Chrome + documentation](https://developer.chrome.com/docs/extensions/mv2/external_extensions). ''; }; }; diff --git a/modules/programs/command-not-found/command-not-found.nix b/modules/programs/command-not-found/command-not-found.nix index a4917bbf..d04711e0 100644 --- a/modules/programs/command-not-found/command-not-found.nix +++ b/modules/programs/command-not-found/command-not-found.nix @@ -31,13 +31,14 @@ let in { options.programs.command-not-found = { - enable = mkEnableOption "command-not-found hook for interactive shell"; + enable = + mkEnableOption (lib.mdDoc "command-not-found hook for interactive shell"); dbPath = mkOption { default = "/nix/var/nix/profiles/per-user/root/channels/nixos/programs.sqlite"; - description = '' - Absolute path to programs.sqlite. By + description = lib.mdDoc '' + Absolute path to {file}`programs.sqlite`. By default this file will be provided by your channel (nixexprs.tar.xz). ''; diff --git a/modules/programs/comodoro.nix b/modules/programs/comodoro.nix index c7b8ea00..7b8c076c 100644 --- a/modules/programs/comodoro.nix +++ b/modules/programs/comodoro.nix @@ -8,16 +8,17 @@ in { meta.maintainers = with lib.hm.maintainers; [ soywod ]; options.programs.comodoro = { - enable = lib.mkEnableOption "Comodoro, a CLI to manage your time"; + enable = + lib.mkEnableOption (lib.mdDoc "Comodoro, a CLI to manage your time"); package = lib.mkPackageOptionMD pkgs "comodoro" { }; settings = lib.mkOption { type = lib.types.submodule { freeformType = tomlFormat.type; }; default = { }; - description = '' + description = lib.mdDoc '' Comodoro configuration. - See for supported values. + See for supported values. ''; }; }; diff --git a/modules/programs/darcs.nix b/modules/programs/darcs.nix index a2a45cba..d01c1dd6 100644 --- a/modules/programs/darcs.nix +++ b/modules/programs/darcs.nix @@ -11,7 +11,7 @@ in { options = { programs.darcs = { - enable = mkEnableOption "darcs"; + enable = mkEnableOption (lib.mdDoc "darcs"); package = mkPackageOption pkgs "darcs" { }; @@ -19,7 +19,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "Fred Bloggs " ]; - description = '' + description = lib.mdDoc '' If this list has a single entry, it will be used as the author when you record a patch. If there are multiple entries, Darcs will prompt you to choose one of them. @@ -30,7 +30,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "^.idea$" ".iml$" "^.stack-work$" ]; - description = "File patterns to ignore"; + description = lib.mdDoc "File patterns to ignore"; }; }; }; diff --git a/modules/programs/dircolors.nix b/modules/programs/dircolors.nix index 6953ab15..5e4e0a39 100644 --- a/modules/programs/dircolors.nix +++ b/modules/programs/dircolors.nix @@ -13,16 +13,16 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' - Whether to manage .dir_colors - and set LS_COLORS. + description = lib.mdDoc '' + Whether to manage {file}`.dir_colors` + and set `LS_COLORS`. ''; }; enableBashIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -30,7 +30,7 @@ in { enableFishIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; @@ -38,7 +38,7 @@ in { enableZshIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -46,9 +46,9 @@ in { settings = mkOption { type = with types; attrsOf str; default = { }; - description = '' - Options to add to .dir_colors file. - See dircolors --print-database + description = lib.mdDoc '' + Options to add to {file}`.dir_colors` file. + See {command}`dircolors --print-database` for options. ''; example = literalExpression '' @@ -63,8 +63,8 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra lines added to .dir_colors file. + description = lib.mdDoc '' + Extra lines added to {file}`.dir_colors` file. ''; }; }; diff --git a/modules/programs/direnv.nix b/modules/programs/direnv.nix index 2e89695f..d96f14db 100644 --- a/modules/programs/direnv.nix +++ b/modules/programs/direnv.nix @@ -22,20 +22,17 @@ in { meta.maintainers = [ maintainers.rycee ]; options.programs.direnv = { - enable = mkEnableOption "direnv, the environment switcher"; + enable = mkEnableOption (lib.mdDoc "direnv, the environment switcher"); config = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/direnv/direnv.toml. - + {file}`$XDG_CONFIG_HOME/direnv/direnv.toml`. + See - - direnv.toml - 1 - . + {manpage}`direnv.toml(1)`. for the full list of options. ''; }; @@ -43,16 +40,16 @@ in { stdlib = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Custom stdlib written to - $XDG_CONFIG_HOME/direnv/direnvrc. + {file}`$XDG_CONFIG_HOME/direnv/direnvrc`. ''; }; enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -60,7 +57,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -69,13 +66,13 @@ in { default = true; type = types.bool; readOnly = true; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. Note, enabling the direnv module will always active its functionality for Fish since the direnv package automatically gets loaded in Fish. If this is not the case try adding - + ```nix environment.pathsToLink = [ "/share/fish" ]; - + ``` to the system configuration. ''; }; @@ -83,7 +80,7 @@ in { enableNushellIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Nushell integration. ''; }; diff --git a/modules/programs/discocss.nix b/modules/programs/discocss.nix index bc0aebd2..b9beb094 100644 --- a/modules/programs/discocss.nix +++ b/modules/programs/discocss.nix @@ -9,7 +9,7 @@ in { options = { programs.discocss = { enable = mkEnableOption - "discocss, a tiny Discord CSS injector for Linux and MacOS"; + (lib.mdDoc "discocss, a tiny Discord CSS injector for Linux and MacOS"); package = mkPackageOptionMD pkgs "discocss" { }; @@ -18,13 +18,13 @@ in { discordAlias = mkOption { type = types.bool; default = true; - description = "Whether to alias discocss to discord."; + description = lib.mdDoc "Whether to alias discocss to discord."; }; css = mkOption { type = types.str; default = ""; - description = "The custom CSS for discocss to use."; + description = lib.mdDoc "The custom CSS for discocss to use."; }; }; }; diff --git a/modules/programs/eclipse.nix b/modules/programs/eclipse.nix index 4c9328a0..d7b4ed8b 100644 --- a/modules/programs/eclipse.nix +++ b/modules/programs/eclipse.nix @@ -11,14 +11,14 @@ in { options = { programs.eclipse = { - enable = mkEnableOption "Eclipse"; + enable = mkEnableOption (lib.mdDoc "Eclipse"); package = mkOption { type = types.package; default = pkgs.eclipses.eclipse-platform; defaultText = literalExpression "pkgs.eclipses.eclipse-platform"; example = literalExpression "pkgs.eclipses.eclipse-java"; - description = '' + description = lib.mdDoc '' The Eclipse package to install. ''; }; @@ -27,7 +27,7 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether to enable the Lombok Java Agent in Eclipse. This is necessary to use the Lombok class annotations. ''; @@ -36,13 +36,13 @@ in { jvmArgs = mkOption { type = types.listOf types.str; default = [ ]; - description = "JVM arguments to use for the Eclipse process."; + description = lib.mdDoc "JVM arguments to use for the Eclipse process."; }; plugins = mkOption { type = types.listOf types.package; default = [ ]; - description = "Plugins that should be added to Eclipse."; + description = lib.mdDoc "Plugins that should be added to Eclipse."; }; }; }; diff --git a/modules/programs/emacs.nix b/modules/programs/emacs.nix index a9a77949..9d1604cb 100644 --- a/modules/programs/emacs.nix +++ b/modules/programs/emacs.nix @@ -28,14 +28,14 @@ in { options = { programs.emacs = { - enable = mkEnableOption "Emacs"; + enable = mkEnableOption (lib.mdDoc "Emacs"); package = mkOption { type = types.package; default = pkgs.emacs; defaultText = literalExpression "pkgs.emacs"; example = literalExpression "pkgs.emacs25-nox"; - description = "The Emacs package to use."; + description = lib.mdDoc "The Emacs package to use."; }; # NOTE: The config is placed in default.el instead of ~/.emacs.d so that @@ -48,12 +48,12 @@ in { example = '' (setq standard-indent 2) ''; - description = '' + description = lib.mdDoc '' Configuration to include in the Emacs default init file. See - + for more. - - Note, the inhibit-startup-message Emacs option + + Note, the `inhibit-startup-message` Emacs option cannot be set here since Emacs disallows setting it from the default initialization file. ''; @@ -64,10 +64,10 @@ in { type = hm.types.selectorFunction; defaultText = "epkgs: []"; example = literalExpression "epkgs: [ epkgs.emms epkgs.magit ]"; - description = '' + description = lib.mdDoc '' Extra packages available to Emacs. To get a list of available packages run: - nix-env -f '<nixpkgs>' -qaP -A emacsPackages. + {command}`nix-env -f '' -qaP -A emacsPackages`. ''; }; @@ -81,7 +81,7 @@ in { # ... }; ''; - description = '' + description = lib.mdDoc '' Allows overriding packages within the Emacs package set. ''; }; @@ -90,7 +90,7 @@ in { type = types.package; visible = false; readOnly = true; - description = '' + description = lib.mdDoc '' The Emacs package including any overrides and extra packages. ''; }; diff --git a/modules/programs/eww.nix b/modules/programs/eww.nix index 9200986d..6a8b680e 100644 --- a/modules/programs/eww.nix +++ b/modules/programs/eww.nix @@ -10,14 +10,14 @@ in { meta.maintainers = [ hm.maintainers.mainrs ]; options.programs.eww = { - enable = mkEnableOption "eww"; + enable = mkEnableOption (lib.mdDoc "eww"); package = mkOption { type = types.package; default = pkgs.eww; defaultText = literalExpression "pkgs.eww"; example = literalExpression "pkgs.eww"; - description = '' + description = lib.mdDoc '' The eww package to install. ''; }; @@ -25,9 +25,9 @@ in { configDir = mkOption { type = types.path; example = literalExpression "./eww-config-dir"; - description = '' + description = lib.mdDoc '' The directory that gets symlinked to - $XDG_CONFIG_HOME/eww. + {file}`$XDG_CONFIG_HOME/eww`. ''; }; }; diff --git a/modules/programs/exa.nix b/modules/programs/exa.nix index 867a74ef..0bcd7563 100644 --- a/modules/programs/exa.nix +++ b/modules/programs/exa.nix @@ -7,15 +7,16 @@ with lib; options.programs.exa = { enable = - mkEnableOption "exa, a modern replacement for ls"; + mkEnableOption (lib.mdDoc "exa, a modern replacement for {command}`ls`"); - enableAliases = mkEnableOption "recommended exa aliases (ls, ll…)"; + enableAliases = + mkEnableOption (lib.mdDoc "recommended exa aliases (ls, ll…)"); extraOptions = mkOption { type = types.listOf types.str; default = [ ]; example = [ "--group-directories-first" "--header" ]; - description = '' + description = lib.mdDoc '' Extra command line options passed to exa. ''; }; @@ -23,16 +24,16 @@ with lib; icons = mkOption { type = types.bool; default = false; - description = '' - Display icons next to file names ( argument). + description = lib.mdDoc '' + Display icons next to file names ({option}`--icons` argument). ''; }; git = mkOption { type = types.bool; default = false; - description = '' - List each file's Git status if tracked or ignored ( argument). + description = lib.mdDoc '' + List each file's Git status if tracked or ignored ({option}`--git` argument). ''; }; diff --git a/modules/programs/feh.nix b/modules/programs/feh.nix index 459c60a5..04cd0600 100644 --- a/modules/programs/feh.nix +++ b/modules/programs/feh.nix @@ -25,7 +25,7 @@ let in { options.programs.feh = { - enable = mkEnableOption "feh - a fast and light image viewer"; + enable = mkEnableOption (lib.mdDoc "feh - a fast and light image viewer"); package = mkPackageOptionMD pkgs "feh" { }; @@ -37,11 +37,11 @@ in { zoom_out = "C-4"; prev_img = [ 3 "C-3" ]; }; - description = '' + description = lib.mdDoc '' Override feh's default mouse button mapping. If you want to disable an action, set its value to null. If you want to bind multiple buttons to an action, set its value to a list. - See for + See for default bindings and available commands. ''; }; @@ -54,11 +54,11 @@ in { zoom_out = "minus"; prev_img = [ "h" "Left" ]; }; - description = '' + description = lib.mdDoc '' Override feh's default keybindings. If you want to disable a keybinding set its value to null. If you want to bind multiple keys to an action, set its value to a list. - See for + See for default bindings and available commands. ''; }; diff --git a/modules/programs/firefox.nix b/modules/programs/firefox.nix index b9d9d2f8..788386db 100644 --- a/modules/programs/firefox.nix +++ b/modules/programs/firefox.nix @@ -134,7 +134,7 @@ in { options = { programs.firefox = { - enable = mkEnableOption "Firefox"; + enable = mkEnableOption (lib.mdDoc "Firefox"); package = mkOption { type = types.package; @@ -154,7 +154,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' The Firefox package to use. If state version ≥ 19.09 then this should be a wrapped Firefox package. For earlier state versions it should be an unwrapped Firefox package. @@ -167,13 +167,13 @@ in { name = mkOption { type = types.str; default = name; - description = "Profile name."; + description = lib.mdDoc "Profile name."; }; id = mkOption { type = types.ints.unsigned; default = 0; - description = '' + description = lib.mdDoc '' Profile ID. This should be set to a unique number per profile. ''; }; @@ -198,7 +198,7 @@ in { }]; } ''; - description = '' + description = lib.mdDoc '' Attribute set of Firefox preferences. Firefox only supports int, bool, and string types for @@ -210,15 +210,15 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra preferences to add to user.js. + description = lib.mdDoc '' + Extra preferences to add to {file}`user.js`. ''; }; userChrome = mkOption { type = types.lines; default = ""; - description = "Custom Firefox user chrome CSS."; + description = lib.mdDoc "Custom Firefox user chrome CSS."; example = '' /* Hide tab bar in FF Quantum */ @-moz-document url("chrome://browser/content/browser.xul") { @@ -237,7 +237,7 @@ in { userContent = mkOption { type = types.lines; default = ""; - description = "Custom Firefox user content CSS."; + description = lib.mdDoc "Custom Firefox user content CSS."; example = '' /* Hide scrollbar in FF Quantum */ *{scrollbar-width:none !important} @@ -251,24 +251,25 @@ in { name = mkOption { type = types.str; default = name; - description = "Bookmark name."; + description = lib.mdDoc "Bookmark name."; }; tags = mkOption { type = types.listOf types.str; default = [ ]; - description = "Bookmark tags."; + description = lib.mdDoc "Bookmark tags."; }; keyword = mkOption { type = types.nullOr types.str; default = null; - description = "Bookmark search keyword."; + description = lib.mdDoc "Bookmark search keyword."; }; url = mkOption { type = types.str; - description = "Bookmark url, use %s for search terms."; + description = + lib.mdDoc "Bookmark url, use %s for search terms."; }; }; }) // { @@ -282,19 +283,20 @@ in { name = mkOption { type = types.str; default = name; - description = "Directory name."; + description = lib.mdDoc "Directory name."; }; bookmarks = mkOption { type = types.listOf nodeType; default = [ ]; - description = "Bookmarks within directory."; + description = lib.mdDoc "Bookmarks within directory."; }; toolbar = mkOption { type = types.bool; default = false; - description = "If directory should be shown in toolbar."; + description = + lib.mdDoc "If directory should be shown in toolbar."; }; }; }) // { @@ -334,7 +336,7 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' Preloaded bookmarks. Note, this may silently overwrite any previously existing bookmarks! ''; @@ -343,21 +345,21 @@ in { path = mkOption { type = types.str; default = name; - description = "Profile path."; + description = lib.mdDoc "Profile path."; }; isDefault = mkOption { type = types.bool; default = config.id == 0; defaultText = "true if profile ID is 0"; - description = "Whether this is a default profile."; + description = lib.mdDoc "Whether this is a default profile."; }; search = { force = mkOption { type = with types; bool; default = false; - description = '' + description = lib.mdDoc '' Whether to force replace the existing search configuration. This is recommended since Firefox will replace the symlink for the search configuration on every @@ -370,7 +372,7 @@ in { type = with types; nullOr str; default = null; example = "DuckDuckGo"; - description = '' + description = lib.mdDoc '' The default search engine used in the address bar and search bar. ''; }; @@ -379,7 +381,7 @@ in { type = with types; uniq (listOf str); default = [ ]; example = [ "DuckDuckGo" "Google" ]; - description = '' + description = lib.mdDoc '' The order the search engines are listed in. Any engines that aren't included in this list will be listed after these in an unspecified order. @@ -415,19 +417,18 @@ in { "Google".metaData.alias = "@g"; # builtin engines only support specifying one additional alias } ''; - description = '' + description = lib.mdDoc '' Attribute set of search engine configurations. Engines - that only have metaData specified will + that only have {var}`metaData` specified will be treated as builtin to Firefox. - - See SearchEngine.jsm + + See [SearchEngine.jsm](https://searchfox.org/mozilla-central/rev/669329e284f8e8e2bb28090617192ca9b4ef3380/toolkit/components/search/SearchEngine.jsm#1138-1177) in Firefox's source for available options. We maintain a mapping to let you specify all options in the referenced link without underscores, but it may fall out of date with future options. - - Note, icon is also a special option + + Note, {var}`icon` is also a special option added by Home Manager to make it convenient to specify absolute icon paths. ''; @@ -462,17 +463,17 @@ in { }; })); default = { }; - description = "Attribute set of Firefox profiles."; + description = lib.mdDoc "Attribute set of Firefox profiles."; }; enableGnomeExtensions = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable the GNOME Shell native host connector. Note, you also need to set the NixOS option - services.gnome.gnome-browser-connector.enable to - true. + `services.gnome.gnome-browser-connector.enable` to + `true`. ''; }; }; diff --git a/modules/programs/fish.nix b/modules/programs/fish.nix index e9bc76e8..a74164fb 100644 --- a/modules/programs/fish.nix +++ b/modules/programs/fish.nix @@ -10,19 +10,19 @@ let options = { src = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to the plugin folder. - + Relevant pieces will be added to the fish function path and - the completion path. The init.fish and - key_binding.fish files are sourced if + the completion path. The {file}`init.fish` and + {file}`key_binding.fish` files are sourced if they exist. ''; }; name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The name of the plugin. ''; }; @@ -33,7 +33,7 @@ let options = { body = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' The function body. ''; }; @@ -41,7 +41,7 @@ let argumentNames = mkOption { type = with types; nullOr (either str (listOf str)); default = null; - description = '' + description = lib.mdDoc '' Assigns the value of successive command line arguments to the names given. ''; @@ -50,7 +50,7 @@ let description = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' A description of what the function does, suitable as a completion description. ''; @@ -59,7 +59,7 @@ let wraps = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Causes the function to inherit completions from the given wrapped command. ''; @@ -68,7 +68,7 @@ let onEvent = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt. @@ -78,7 +78,7 @@ let onVariable = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Tells fish to run this function when the specified variable changes value. ''; @@ -87,9 +87,9 @@ let onJobExit = mkOption { type = with types; nullOr (either str int); default = null; - description = '' + description = lib.mdDoc '' Tells fish to run this function when the job with the specified group - ID exits. Instead of a PID, the stringer caller can + ID exits. Instead of a PID, the stringer `caller` can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution. @@ -100,11 +100,11 @@ let type = with types; nullOr (either str int); default = null; example = "$fish_pid"; - description = '' + description = lib.mdDoc '' Tells fish to run this function when the fish child process with the specified process ID exits. Instead of a PID, for backwards - compatibility, %self can be specified as an alias - for $fish_pid, and the function will be run when + compatibility, `%self` can be specified as an alias + for `$fish_pid`, and the function will be run when the current fish instance exits. ''; }; @@ -113,7 +113,7 @@ let type = with types; nullOr (either str int); default = null; example = [ "SIGHUP" "HUP" 1 ]; - description = '' + description = lib.mdDoc '' Tells fish to run this function when the specified signal is delievered. The signal can be a signal number or signal name. ''; @@ -122,7 +122,7 @@ let noScopeShadowing = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Allows the function to access the variables of calling functions. ''; }; @@ -130,7 +130,7 @@ let inheritVariable = mkOption { type = with types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' Snapshots the value of the specified variable and defines a local variable with that same name and value when the function is defined. ''; @@ -172,13 +172,14 @@ in { options = { programs.fish = { - enable = mkEnableOption "fish, the friendly interactive shell"; + enable = + mkEnableOption (lib.mdDoc "fish, the friendly interactive shell"); package = mkOption { type = types.package; default = pkgs.fish; defaultText = literalExpression "pkgs.fish"; - description = '' + description = lib.mdDoc '' The fish package to install. May be used to change the version. ''; }; @@ -192,7 +193,7 @@ in { "..." = "cd ../.."; } ''; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. ''; @@ -205,7 +206,7 @@ in { l = "less"; gco = "git checkout"; }; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to abbreviations. Abbreviations are expanded with the longer phrase after they are entered. @@ -215,7 +216,7 @@ in { shellInit = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Shell script code called during fish shell initialisation. ''; @@ -224,7 +225,7 @@ in { loginShellInit = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Shell script code called during fish login shell initialisation. ''; @@ -233,7 +234,7 @@ in { interactiveShellInit = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Shell script code called during interactive fish shell initialisation. ''; @@ -268,9 +269,9 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' The plugins to source in - conf.d/99plugins.fish. + {file}`conf.d/99plugins.fish`. ''; }; @@ -287,9 +288,9 @@ in { gitignore = "curl -sL https://www.gitignore.io/api/$argv"; } ''; - description = '' + description = lib.mdDoc '' Basic functions to add to fish. For more information see - . + . ''; }; }; diff --git a/modules/programs/foot.nix b/modules/programs/foot.nix index 2b08f3ac..7a4ff79a 100644 --- a/modules/programs/foot.nix +++ b/modules/programs/foot.nix @@ -11,24 +11,23 @@ in { meta.maintainers = with lib.maintainers; [ plabadens ]; options.programs.foot = { - enable = mkEnableOption "Foot terminal"; + enable = mkEnableOption (lib.mdDoc "Foot terminal"); package = mkOption { type = types.package; default = pkgs.foot; defaultText = literalExpression "pkgs.foot"; - description = "The foot package to install"; + description = lib.mdDoc "The foot package to install"; }; - server.enable = mkEnableOption "Foot terminal server"; + server.enable = mkEnableOption (lib.mdDoc "Foot terminal server"); settings = mkOption { type = iniFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/foot/foot.ini. See + {file}`$XDG_CONFIG_HOME/foot/foot.ini`. See for a list of available options. ''; example = literalExpression '' diff --git a/modules/programs/fuzzel.nix b/modules/programs/fuzzel.nix index e8205e93..22863281 100644 --- a/modules/programs/fuzzel.nix +++ b/modules/programs/fuzzel.nix @@ -13,7 +13,7 @@ in { meta.maintainers = [ lib.maintainers.Scrumplex ]; options.programs.fuzzel = { - enable = mkEnableOption "fuzzel"; + enable = mkEnableOption (lib.mdDoc "fuzzel"); package = mkPackageOptionMD pkgs "fuzzel" { }; @@ -29,11 +29,10 @@ in { colors.background = "ffffffff"; } ''; - description = '' + description = lib.mdDoc '' Configuration for fuzzel written to - $XDG_CONFIG_HOME/fuzzel/fuzzel.ini. See - fuzzel.ini - 5 for a list of available options. + {file}`$XDG_CONFIG_HOME/fuzzel/fuzzel.ini`. See + {manpage}`fuzzel.ini(5)` for a list of available options. ''; }; }; diff --git a/modules/programs/fzf.nix b/modules/programs/fzf.nix index b572d0a5..a19e29c8 100644 --- a/modules/programs/fzf.nix +++ b/modules/programs/fzf.nix @@ -17,20 +17,20 @@ in { ]; options.programs.fzf = { - enable = mkEnableOption "fzf - a command-line fuzzy finder"; + enable = mkEnableOption (lib.mdDoc "fzf - a command-line fuzzy finder"); package = mkOption { type = types.package; default = pkgs.fzf; defaultText = literalExpression "pkgs.fzf"; - description = "Package providing the fzf tool."; + description = lib.mdDoc "Package providing the {command}`fzf` tool."; }; defaultCommand = mkOption { type = types.nullOr types.str; default = null; example = "fd --type f"; - description = '' + description = lib.mdDoc '' The command that gets executed as the default source for fzf when running. ''; @@ -40,7 +40,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--height 40%" "--border" ]; - description = '' + description = lib.mdDoc '' Extra command line options given to fzf by default. ''; }; @@ -49,7 +49,7 @@ in { type = types.nullOr types.str; default = null; example = "fd --type f"; - description = '' + description = lib.mdDoc '' The command that gets executed as the source for fzf for the CTRL-T keybinding. ''; @@ -59,7 +59,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--preview 'head {}'" ]; - description = '' + description = lib.mdDoc '' Command line options for the CTRL-T keybinding. ''; }; @@ -68,7 +68,7 @@ in { type = types.nullOr types.str; default = null; example = "fd --type d"; - description = '' + description = lib.mdDoc '' The command that gets executed as the source for fzf for the ALT-C keybinding. ''; @@ -78,7 +78,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--preview 'tree -C {} | head -200'" ]; - description = '' + description = lib.mdDoc '' Command line options for the ALT-C keybinding. ''; }; @@ -87,7 +87,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--sort" "--exact" ]; - description = '' + description = lib.mdDoc '' Command line options for the CTRL-R keybinding. ''; }; @@ -103,26 +103,26 @@ in { "fg+" = "#d4d4d4"; } ''; - description = '' - Color scheme options added to FZF_DEFAULT_OPTS. See - + description = lib.mdDoc '' + Color scheme options added to `FZF_DEFAULT_OPTS`. See + for documentation. ''; }; tmux = { - enableShellIntegration = mkEnableOption '' - setting FZF_TMUX=1 which causes shell integration to use fzf-tmux - ''; + enableShellIntegration = mkEnableOption (lib.mdDoc '' + setting `FZF_TMUX=1` which causes shell integration to use fzf-tmux + ''); shellIntegrationOptions = mkOption { type = types.listOf types.str; default = [ ]; example = literalExpression ''[ "-d 40%" ]''; - description = '' - If is set to true, + description = lib.mdDoc '' + If {option}`programs.fzf.tmux.enableShellIntegration` is set to `true`, shell integration will use these options for fzf-tmux. - See fzf-tmux --help for available options. + See {command}`fzf-tmux --help` for available options. ''; }; }; @@ -130,7 +130,7 @@ in { enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -138,7 +138,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -146,7 +146,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/gallery-dl.nix b/modules/programs/gallery-dl.nix index 560ec8e9..0d32ee3e 100644 --- a/modules/programs/gallery-dl.nix +++ b/modules/programs/gallery-dl.nix @@ -12,7 +12,7 @@ in { meta.maintainers = [ ]; options.programs.gallery-dl = { - enable = mkEnableOption "gallery-dl"; + enable = mkEnableOption (lib.mdDoc "gallery-dl"); settings = mkOption { type = jsonFormat.type; @@ -22,10 +22,10 @@ in { extractor.base-directory = "~/Downloads"; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/gallery-dl/config.json. See - + {file}`$XDG_CONFIG_HOME/gallery-dl/config.json`. See + for supported values. ''; }; diff --git a/modules/programs/getmail-accounts.nix b/modules/programs/getmail-accounts.nix index 24eb4fb5..6cf8ac10 100644 --- a/modules/programs/getmail-accounts.nix +++ b/modules/programs/getmail-accounts.nix @@ -4,13 +4,14 @@ with lib; { options.getmail = { - enable = mkEnableOption "the getmail mail retriever for this account"; + enable = + mkEnableOption (lib.mdDoc "the getmail mail retriever for this account"); destinationCommand = mkOption { type = types.nullOr types.str; default = null; example = "\${pkgs.maildrop}/bin/maildrop"; - description = '' + description = lib.mdDoc '' Specify a command delivering the incoming mail to your maildir. ''; }; @@ -19,29 +20,29 @@ with lib; type = types.nonEmptyListOf types.str; default = [ ]; example = [ "INBOX" "INBOX.spam" ]; - description = '' + description = lib.mdDoc '' A non-empty list of mailboxes. To download all mail you can - use the ALL mailbox. + use the `ALL` mailbox. ''; }; delete = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable if you want to delete read messages from the server. Most - users should either enable delete or disable - readAll. + users should either enable `delete` or disable + `readAll`. ''; }; readAll = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable if you want to fetch all, even the read messages from the - server. Most users should either enable delete or - disable readAll. + server. Most users should either enable `delete` or + disable `readAll`. ''; }; diff --git a/modules/programs/gh.nix b/modules/programs/gh.nix index 920dd643..7dd162cf 100644 --- a/modules/programs/gh.nix +++ b/modules/programs/gh.nix @@ -21,14 +21,14 @@ let pv = "pr view"; } ''; - description = '' + description = lib.mdDoc '' Aliases that allow you to create nicknames for gh commands. ''; }; editor = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' The editor that gh should run when creating issues, pull requests, etc. If blank, will refer to environment. ''; @@ -37,7 +37,7 @@ let type = types.str; default = "https"; example = "ssh"; - description = '' + description = lib.mdDoc '' The protocol to use when performing Git operations. ''; }; @@ -63,20 +63,20 @@ in { ]; options.programs.gh = { - enable = mkEnableOption "GitHub CLI tool"; + enable = mkEnableOption (lib.mdDoc "GitHub CLI tool"); package = mkOption { type = types.package; default = pkgs.gh; defaultText = literalExpression "pkgs.gh"; - description = "Package providing gh."; + description = lib.mdDoc "Package providing {command}`gh`."; }; settings = mkOption { type = settingsType; default = { }; - description = - "Configuration written to $XDG_CONFIG_HOME/gh/config.yml."; + description = lib.mdDoc + "Configuration written to {file}`$XDG_CONFIG_HOME/gh/config.yml`."; example = literalExpression '' { git_protocol = "ssh"; @@ -92,15 +92,16 @@ in { }; enableGitCredentialHelper = - mkEnableOption "the gh git credential helper for github.com" // { + mkEnableOption (lib.mdDoc "the gh git credential helper for github.com") + // { default = true; }; extensions = mkOption { type = types.listOf types.package; default = [ ]; - description = '' - gh extensions, see . + description = lib.mdDoc '' + gh extensions, see . ''; example = literalExpression "[ pkgs.gh-eco ]"; }; diff --git a/modules/programs/git-cliff.nix b/modules/programs/git-cliff.nix index e9460d51..b3de2233 100644 --- a/modules/programs/git-cliff.nix +++ b/modules/programs/git-cliff.nix @@ -11,7 +11,7 @@ in { meta.maintainers = [ hm.maintainers.NateCox ]; options.programs.git-cliff = { - enable = mkEnableOption "git-cliff changelog generator"; + enable = mkEnableOption (lib.mdDoc "git-cliff changelog generator"); package = mkPackageOptionMD pkgs "git-cliff" { }; @@ -24,10 +24,10 @@ in { trim = true; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/git-cliff/cliff.toml. See - + {file}`$XDG_CONFIG_HOME/git-cliff/cliff.toml`. See + for the documentation. ''; }; diff --git a/modules/programs/git-credential-oauth.nix b/modules/programs/git-credential-oauth.nix index 8f260d09..b1b1c5b9 100644 --- a/modules/programs/git-credential-oauth.nix +++ b/modules/programs/git-credential-oauth.nix @@ -9,7 +9,8 @@ in { options = { programs.git-credential-oauth = { - enable = lib.mkEnableOption "Git authentication handler for OAuth"; + enable = + lib.mkEnableOption (lib.mdDoc "Git authentication handler for OAuth"); package = lib.mkPackageOptionMD pkgs "git-credential-oauth" { }; }; diff --git a/modules/programs/git.nix b/modules/programs/git.nix index 40052d17..bae2e40d 100644 --- a/modules/programs/git.nix +++ b/modules/programs/git.nix @@ -62,10 +62,10 @@ let options = { key = mkOption { type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The default GPG signing key fingerprint. - - Set to null to let GnuPG decide what signing key + + Set to `null` to let GnuPG decide what signing key to use depending on commit’s author. ''; }; @@ -73,14 +73,15 @@ let signByDefault = mkOption { type = types.bool; default = false; - description = "Whether commits and tags should be signed by default."; + description = + lib.mdDoc "Whether commits and tags should be signed by default."; }; gpgPath = mkOption { type = types.str; default = "${pkgs.gnupg}/bin/gpg2"; defaultText = "\${pkgs.gnupg}/bin/gpg2"; - description = "Path to GnuPG binary to use."; + description = lib.mdDoc "Path to GnuPG binary to use."; }; }; }; @@ -90,19 +91,16 @@ let condition = mkOption { type = types.nullOr types.str; default = null; - description = '' - Include this configuration only when condition + description = lib.mdDoc '' + Include this configuration only when {var}`condition` matches. Allowed conditions are described in - - git-config - 1 - . + {manpage}`git-config(1)`. ''; }; path = mkOption { type = with types; either str path; - description = "Path of the configuration file to include."; + description = lib.mdDoc "Path of the configuration file to include."; }; contents = mkOption { @@ -120,21 +118,18 @@ let }; }; ''; - description = '' + description = lib.mdDoc '' Configuration to include. If empty then a path must be given. This follows the configuration structure as described in - - git-config - 1 - . + {manpage}`git-config(1)`. ''; }; contentSuffix = mkOption { type = types.str; default = "gitconfig"; - description = '' + description = lib.mdDoc '' Nix store name for the git configuration text file, when generating the configuration text from nix options. ''; @@ -151,41 +146,42 @@ in { options = { programs.git = { - enable = mkEnableOption "Git"; + enable = mkEnableOption (lib.mdDoc "Git"); package = mkOption { type = types.package; default = pkgs.git; defaultText = literalExpression "pkgs.git"; - description = '' - Git package to install. Use pkgs.gitAndTools.gitFull - to gain access to git send-email for instance. + description = lib.mdDoc '' + Git package to install. Use {var}`pkgs.gitAndTools.gitFull` + to gain access to {command}`git send-email` for instance. ''; }; userName = mkOption { type = types.nullOr types.str; default = null; - description = "Default user name to use."; + description = lib.mdDoc "Default user name to use."; }; userEmail = mkOption { type = types.nullOr types.str; default = null; - description = "Default user email to use."; + description = lib.mdDoc "Default user email to use."; }; aliases = mkOption { type = types.attrsOf types.str; default = { }; example = { co = "checkout"; }; - description = "Git aliases to define."; + description = lib.mdDoc "Git aliases to define."; }; signing = mkOption { type = types.nullOr signModule; default = null; - description = "Options related to signing commits using GnuPG."; + description = + lib.mdDoc "Options related to signing commits using GnuPG."; }; extraConfig = mkOption { @@ -195,7 +191,7 @@ in { core = { whitespace = "trailing-space,space-before-tab"; }; url."ssh://git@host".insteadOf = "otherhost"; }; - description = '' + description = lib.mdDoc '' Additional configuration to add. The use of string values is deprecated and will be removed in the future. ''; @@ -209,9 +205,9 @@ in { pre-commit = ./pre-commit-script; } ''; - description = '' + description = lib.mdDoc '' Configuration helper for Git hooks. - See + See for reference. ''; }; @@ -225,14 +221,15 @@ in { type = types.listOf types.str; default = [ ]; example = [ "*~" "*.swp" ]; - description = "List of paths that should be globally ignored."; + description = + lib.mdDoc "List of paths that should be globally ignored."; }; attributes = mkOption { type = types.listOf types.str; default = [ ]; example = [ "*.pdf diff=pdf" ]; - description = "List of defining attributes set globally."; + description = lib.mdDoc "List of defining attributes set globally."; }; includes = mkOption { @@ -247,18 +244,18 @@ in { } ] ''; - description = "List of configuration files to include."; + description = lib.mdDoc "List of configuration files to include."; }; lfs = { - enable = mkEnableOption "Git Large File Storage"; + enable = mkEnableOption (lib.mdDoc "Git Large File Storage"); skipSmudge = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Skip automatic downloading of objects on clone or pull. - This requires a manual git lfs pull + This requires a manual {command}`git lfs pull` every time a new commit is checked out on your repository. ''; }; @@ -276,7 +273,7 @@ in { type = types.enum [ "light" "dark" ]; default = "light"; example = "dark"; - description = '' + description = lib.mdDoc '' Determines whether difftastic should use the lighter or darker colors for syntax highlighting. ''; @@ -286,7 +283,7 @@ in { type = types.enum [ "always" "auto" "never" ]; default = "auto"; example = "always"; - description = '' + description = lib.mdDoc '' Determines when difftastic should color its output. ''; }; @@ -296,7 +293,7 @@ in { types.enum [ "side-by-side" "side-by-side-show-both" "inline" ]; default = "side-by-side"; example = "inline"; - description = '' + description = lib.mdDoc '' Determines how the output displays - in one column or two columns. ''; }; @@ -328,7 +325,7 @@ in { file-decoration-style = "none"; }; }; - description = '' + description = lib.mdDoc '' Options to configure delta. ''; }; @@ -345,8 +342,8 @@ in { pagerOpts = mkOption { type = types.listOf types.str; default = [ "--tabs=4" "-RFX" ]; - description = '' - Arguments to be passed to less. + description = lib.mdDoc '' + Arguments to be passed to {command}`less`. ''; }; @@ -354,7 +351,7 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' Whether the first block of an empty line should be colored. ''; }; @@ -363,7 +360,7 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' Simplify git header chunks to a more human readable format. ''; }; @@ -372,8 +369,8 @@ in { type = types.bool; default = true; example = false; - description = '' - Whether the + or - at + description = lib.mdDoc '' + Whether the `+` or `-` at line-start should be removed. ''; }; @@ -382,7 +379,7 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' By default, the separator for the file header uses Unicode line-drawing characters. If this is causing output errors on your terminal, set this to false to use ASCII characters instead. @@ -393,7 +390,7 @@ in { type = types.nullOr types.int; default = null; example = false; - description = '' + description = lib.mdDoc '' By default, the separator for the file header spans the full width of the terminal. Use this setting to set the width of the file header manually. diff --git a/modules/programs/gitui.nix b/modules/programs/gitui.nix index 710e3fd9..f513d4be 100644 --- a/modules/programs/gitui.nix +++ b/modules/programs/gitui.nix @@ -10,14 +10,14 @@ in { meta.maintainers = [ hm.maintainers.mifom ]; options.programs.gitui = { - enable = - mkEnableOption "gitui, blazing fast terminal-ui for git written in rust"; + enable = mkEnableOption + (lib.mdDoc "gitui, blazing fast terminal-ui for git written in rust"); package = mkOption { type = types.package; default = pkgs.gitui; defaultText = "pkgs.gitui"; - description = "The package to use."; + description = lib.mdDoc "The package to use."; }; keyConfig = mkOption { @@ -28,9 +28,9 @@ in { quit: Some(( code: Char('q'), modifiers: ( bits: 0,),)), exit_popup: Some(( code: Esc, modifiers: ( bits: 0,),)), ''; - description = '' + description = lib.mdDoc '' Key config in Ron file format. This is written to - $XDG_CONFIG_HOME/gitui/key_config.ron. + {file}`$XDG_CONFIG_HOME/gitui/key_config.ron`. ''; }; @@ -61,9 +61,9 @@ in { branch_fg: LightYellow, ) ''; - description = '' + description = lib.mdDoc '' Theme in Ron file format. This is written to - $XDG_CONFIG_HOME/gitui/theme.ron. + {file}`$XDG_CONFIG_HOME/gitui/theme.ron`. ''; }; }; diff --git a/modules/programs/gnome-terminal.nix b/modules/programs/gnome-terminal.nix index 8ff161c6..ebaa06c8 100644 --- a/modules/programs/gnome-terminal.nix +++ b/modules/programs/gnome-terminal.nix @@ -18,12 +18,12 @@ let options = { foreground = mkOption { type = types.str; - description = "The foreground color."; + description = lib.mdDoc "The foreground color."; }; background = mkOption { type = types.str; - description = "The background color."; + description = lib.mdDoc "The background color."; }; }; }); @@ -32,35 +32,37 @@ let options = { foregroundColor = mkOption { type = types.str; - description = "The foreground color."; + description = lib.mdDoc "The foreground color."; }; backgroundColor = mkOption { type = types.str; - description = "The background color."; + description = lib.mdDoc "The background color."; }; boldColor = mkOption { default = null; type = types.nullOr types.str; - description = "The bold color, null to use same as foreground."; + description = + lib.mdDoc "The bold color, null to use same as foreground."; }; palette = mkOption { type = types.listOf types.str; - description = "The terminal palette."; + description = lib.mdDoc "The terminal palette."; }; cursor = mkOption { default = null; type = types.nullOr backForeSubModule; - description = "The color for the terminal cursor."; + description = lib.mdDoc "The color for the terminal cursor."; }; highlight = mkOption { default = null; type = types.nullOr backForeSubModule; - description = "The colors for the terminal’s highlighted area."; + description = + lib.mdDoc "The colors for the terminal’s highlighted area."; }; }; }); @@ -70,43 +72,44 @@ let default = mkOption { default = false; type = types.bool; - description = "Whether this should be the default profile."; + description = lib.mdDoc "Whether this should be the default profile."; }; visibleName = mkOption { type = types.str; - description = "The profile name."; + description = lib.mdDoc "The profile name."; }; colors = mkOption { default = null; type = types.nullOr profileColorsSubModule; - description = "The terminal colors, null to use system default."; + description = + lib.mdDoc "The terminal colors, null to use system default."; }; cursorBlinkMode = mkOption { default = "system"; type = types.enum [ "system" "on" "off" ]; - description = "The cursor blink mode."; + description = lib.mdDoc "The cursor blink mode."; }; cursorShape = mkOption { default = "block"; type = types.enum [ "block" "ibeam" "underline" ]; - description = "The cursor shape."; + description = lib.mdDoc "The cursor shape."; }; font = mkOption { default = null; type = types.nullOr types.str; - description = "The font name, null to use system default."; + description = lib.mdDoc "The font name, null to use system default."; }; allowBold = mkOption { default = null; type = types.nullOr types.bool; - description = '' - If true, allow applications in the + description = lib.mdDoc '' + If `true`, allow applications in the terminal to make text boldface. ''; }; @@ -114,19 +117,19 @@ let scrollOnOutput = mkOption { default = true; type = types.bool; - description = "Whether to scroll when output is written."; + description = lib.mdDoc "Whether to scroll when output is written."; }; showScrollbar = mkOption { default = true; type = types.bool; - description = "Whether the scroll bar should be visible."; + description = lib.mdDoc "Whether the scroll bar should be visible."; }; scrollbackLines = mkOption { default = 10000; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' The number of scrollback lines to keep, null for infinite. ''; }; @@ -134,7 +137,7 @@ let customCommand = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' The command to use to start the shell, or null for default shell. ''; }; @@ -142,7 +145,7 @@ let loginShell = mkOption { default = false; type = types.bool; - description = "Run command as a login shell."; + description = lib.mdDoc "Run command as a login shell."; }; backspaceBinding = mkOption { @@ -172,7 +175,7 @@ let boldIsBright = mkOption { default = null; type = types.nullOr types.bool; - description = "Whether bold text is shown in bright colors."; + description = lib.mdDoc "Whether bold text is shown in bright colors."; }; deleteBinding = mkOption { @@ -202,13 +205,13 @@ let audibleBell = mkOption { default = true; type = types.bool; - description = "Turn on/off the terminal's bell."; + description = lib.mdDoc "Turn on/off the terminal's bell."; }; transparencyPercent = mkOption { default = null; type = types.nullOr (types.ints.between 0 100); - description = "Background transparency in percent."; + description = lib.mdDoc "Background transparency in percent."; }; }; }); @@ -275,24 +278,24 @@ in { options = { programs.gnome-terminal = { - enable = mkEnableOption "Gnome Terminal"; + enable = mkEnableOption (lib.mdDoc "Gnome Terminal"); showMenubar = mkOption { default = true; type = types.bool; - description = "Whether to show the menubar by default"; + description = lib.mdDoc "Whether to show the menubar by default"; }; themeVariant = mkOption { default = "default"; type = types.enum [ "default" "light" "dark" "system" ]; - description = "The theme variation to request"; + description = lib.mdDoc "The theme variation to request"; }; profile = mkOption { default = { }; type = types.attrsOf profileSubModule; - description = "A set of Gnome Terminal profiles."; + description = lib.mdDoc "A set of Gnome Terminal profiles."; }; }; }; diff --git a/modules/programs/go.nix b/modules/programs/go.nix index 70a5c9b6..7816e1a3 100644 --- a/modules/programs/go.nix +++ b/modules/programs/go.nix @@ -11,13 +11,13 @@ in { options = { programs.go = { - enable = mkEnableOption "Go"; + enable = mkEnableOption (lib.mdDoc "Go"); package = mkOption { type = types.package; default = pkgs.go; defaultText = literalExpression "pkgs.go"; - description = "The Go package to use."; + description = lib.mdDoc "The Go package to use."; }; packages = mkOption { @@ -29,16 +29,16 @@ in { "golang.org/x/time" = builtins.fetchGit "https://go.googlesource.com/time"; } ''; - description = "Packages to add to GOPATH."; + description = lib.mdDoc "Packages to add to GOPATH."; }; goPath = mkOption { type = with types; nullOr str; default = null; example = "go"; - description = '' - Primary GOPATH relative to - HOME. It will be exported first and therefore + description = lib.mdDoc '' + Primary {env}`GOPATH` relative to + {env}`HOME`. It will be exported first and therefore used by default by the Go tooling. ''; }; @@ -47,9 +47,9 @@ in { type = types.listOf types.str; default = [ ]; example = [ "extraGoPath1" "extraGoPath2" ]; - description = '' - Extra GOPATHs relative to HOME appended - after , if that option is set. + description = lib.mdDoc '' + Extra {env}`GOPATH`s relative to {env}`HOME` appended + after [](#opt-programs.go.goPath), if that option is set. ''; }; @@ -57,15 +57,15 @@ in { type = with types; nullOr str; default = null; example = ".local/bin.go"; - description = "GOBIN relative to HOME"; + description = lib.mdDoc "GOBIN relative to HOME"; }; goPrivate = mkOption { type = with types; listOf str; default = [ ]; example = [ "*.corp.example.com" "rsc.io/private" ]; - description = '' - The GOPRIVATE environment variable controls + description = lib.mdDoc '' + The {env}`GOPRIVATE` environment variable controls which modules the go command considers to be private (not available publicly) and should therefore not use the proxy or checksum database. diff --git a/modules/programs/gpg.nix b/modules/programs/gpg.nix index 3e62995c..3c1e061c 100644 --- a/modules/programs/gpg.nix +++ b/modules/programs/gpg.nix @@ -25,14 +25,14 @@ let text = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Text of an OpenPGP public key. ''; }; source = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path of an OpenPGP public key file. ''; }; @@ -139,7 +139,7 @@ let in { options.programs.gpg = { - enable = mkEnableOption "GnuPG"; + enable = mkEnableOption (lib.mdDoc "GnuPG"); package = mkOption { type = types.package; @@ -147,7 +147,7 @@ in { defaultText = literalExpression "pkgs.gnupg"; example = literalExpression "pkgs.gnupg23"; description = - "The Gnupg package to use (also used the gpg-agent service)."; + lib.mdDoc "The Gnupg package to use (also used the gpg-agent service)."; }; settings = mkOption { @@ -159,17 +159,13 @@ in { s2k-cipher-algo = "AES128"; } ''; - description = '' + description = lib.mdDoc '' GnuPG configuration options. Available options are described in - - - gpg - 1 - - . - - + [ + {manpage}`gpg(1)` + ](https://gnupg.org/documentation/manpage.html). + Note that lists are converted to duplicate keys. ''; }; @@ -182,15 +178,12 @@ in { disable-ccid = true; } ''; - description = '' + description = lib.mdDoc '' SCdaemon configuration options. Available options are described in - - - scdaemon - 1 - - . + [ + {manpage}`scdaemon(1)` + ](https://www.gnupg.org/documentation/manuals/gnupg/Scdaemon-Options.html). ''; }; @@ -200,19 +193,19 @@ in { default = "${config.home.homeDirectory}/.gnupg"; defaultText = literalExpression ''"''${config.home.homeDirectory}/.gnupg"''; - description = "Directory to store keychains and configuration."; + description = lib.mdDoc "Directory to store keychains and configuration."; }; mutableKeys = mkOption { type = types.bool; default = true; - description = '' - If set to true, you may manage your keyring as a user - using the gpg command. Upon activation, the keyring + description = lib.mdDoc '' + If set to `true`, you may manage your keyring as a user + using the `gpg` command. Upon activation, the keyring will have managed keys added without overwriting unmanaged keys. - - If set to false, the path - $GNUPGHOME/pubring.kbx will become an immutable + + If set to `false`, the path + {file}`$GNUPGHOME/pubring.kbx` will become an immutable link to the Nix store, denying modifications. ''; }; @@ -220,16 +213,16 @@ in { mutableTrust = mkOption { type = types.bool; default = true; - description = '' - If set to true, you may manage trust as a user using - the gpg command. Upon activation, trusted keys have + description = lib.mdDoc '' + If set to `true`, you may manage trust as a user using + the {command}`gpg` command. Upon activation, trusted keys have their trust set without overwriting unmanaged keys. - - If set to false, the path - $GNUPGHOME/trustdb.gpg will be - overwritten on each activation, removing trust for + + If set to `false`, the path + {file}`$GNUPGHOME/trustdb.gpg` will be + *overwritten* on each activation, removing trust for any unmanaged keys. Be careful to make a backup of your old - trustdb.gpg before switching to immutable trust! + {file}`trustdb.gpg` before switching to immutable trust! ''; }; @@ -239,7 +232,7 @@ in { [ { source = ./pubkeys.txt; } ] ''; default = [ ]; - description = '' + description = lib.mdDoc '' A list of public keys to be imported into GnuPG. Note, these key files will be copied into the world-readable Nix store. ''; diff --git a/modules/programs/havoc.nix b/modules/programs/havoc.nix index 5e3cbe84..ffb42181 100644 --- a/modules/programs/havoc.nix +++ b/modules/programs/havoc.nix @@ -11,17 +11,16 @@ in { meta.maintainers = with lib.maintainers; [ AndersonTorres ]; options.programs.havoc = { - enable = mkEnableOption "Havoc terminal"; + enable = mkEnableOption (lib.mdDoc "Havoc terminal"); package = mkPackageOptionMD pkgs "havoc" { }; settings = mkOption { type = iniFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/havoc.cfg. See + {file}`$XDG_CONFIG_HOME/havoc.cfg`. See for a list of available options. ''; example = literalExpression '' diff --git a/modules/programs/helix.nix b/modules/programs/helix.nix index 1f3e6249..657a6572 100644 --- a/modules/programs/helix.nix +++ b/modules/programs/helix.nix @@ -9,21 +9,21 @@ in { meta.maintainers = [ hm.maintainers.Philipp-M ]; options.programs.helix = { - enable = mkEnableOption "helix text editor"; + enable = mkEnableOption (lib.mdDoc "helix text editor"); package = mkOption { type = types.package; default = pkgs.helix; defaultText = literalExpression "pkgs.helix"; - description = "The package to use for helix."; + description = lib.mdDoc "The package to use for helix."; }; defaultEditor = mkOption { type = types.bool; default = false; - description = '' - Whether to configure hx as the default - editor using the EDITOR environment variable. + description = lib.mdDoc '' + Whether to configure {command}`hx` as the default + editor using the {env}`EDITOR` environment variable. ''; }; @@ -45,11 +45,11 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/helix/config.toml. - - See + {file}`$XDG_CONFIG_HOME/helix/config.toml`. + + See for the full list of options. ''; }; @@ -80,11 +80,11 @@ in { }]; } ''; - description = '' + description = lib.mdDoc '' Language specific configuration at - $XDG_CONFIG_HOME/helix/languages.toml. - - See + {file}`$XDG_CONFIG_HOME/helix/languages.toml`. + + See for more information. ''; }; @@ -149,12 +149,12 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Each theme is written to - $XDG_CONFIG_HOME/helix/themes/theme-name.toml. + {file}`$XDG_CONFIG_HOME/helix/themes/theme-name.toml`. Where the name of each attribute is the theme-name (in the example "base16"). - - See + + See for the full list of options. ''; }; diff --git a/modules/programs/hexchat.nix b/modules/programs/hexchat.nix index 17e66974..2f22b6a8 100644 --- a/modules/programs/hexchat.nix +++ b/modules/programs/hexchat.nix @@ -11,37 +11,37 @@ let autoconnect = mkOption { type = nullOr bool; default = false; - description = "Autoconnect to network."; + description = lib.mdDoc "Autoconnect to network."; }; connectToSelectedServerOnly = mkOption { type = nullOr bool; default = true; - description = "Connect to selected server only."; + description = lib.mdDoc "Connect to selected server only."; }; bypassProxy = mkOption { type = nullOr bool; default = true; - description = "Bypass proxy."; + description = lib.mdDoc "Bypass proxy."; }; forceSSL = mkOption { type = nullOr bool; default = false; - description = "Use SSL for all servers."; + description = lib.mdDoc "Use SSL for all servers."; }; acceptInvalidSSLCertificates = mkOption { type = nullOr bool; default = false; - description = "Accept invalid SSL certificates."; + description = lib.mdDoc "Accept invalid SSL certificates."; }; useGlobalUserInformation = mkOption { type = nullOr bool; default = false; - description = "Use global user information."; + description = lib.mdDoc "Use global user information."; }; }; }; @@ -53,21 +53,23 @@ let type = listOf str; default = [ ]; example = [ "#home-manager" "#linux" "#nix" ]; - description = "Channels list to autojoin on connecting to server."; + description = + lib.mdDoc "Channels list to autojoin on connecting to server."; }; charset = mkOption { type = nullOr str; default = null; example = "UTF-8 (Unicode)"; - description = "Character set."; + description = lib.mdDoc "Character set."; }; commands = mkOption { type = listOf str; default = [ ]; example = literalExpression ''[ "ECHO Greetings fellow Nixer! ]''; - description = "Commands to be executed on connecting to server."; + description = + lib.mdDoc "Commands to be executed on connecting to server."; }; loginMethod = mkOption { @@ -108,13 +110,13 @@ let nickname = mkOption { type = nullOr str; default = null; - description = "Primary nickname."; + description = lib.mdDoc "Primary nickname."; }; nickname2 = mkOption { type = nullOr str; default = null; - description = "Secondary nickname."; + description = lib.mdDoc "Secondary nickname."; }; options = mkOption { @@ -124,13 +126,13 @@ let autoconnect = true; useGlobalUserInformation = true; }; - description = "Channel options."; + description = lib.mdDoc "Channel options."; }; password = mkOption { type = nullOr str; default = null; - description = '' + description = lib.mdDoc '' Password to use. Note this password will be readable by all user's in the Nix store. ''; @@ -139,17 +141,17 @@ let realName = mkOption { type = nullOr str; default = null; - description = '' + description = lib.mdDoc '' Real name. Is used to populate the real name field that appears when - someone uses the WHOIS command on your nick. + someone uses the `WHOIS` command on your nick. ''; }; userName = mkOption { type = nullOr str; default = null; - description = '' - User name. Part of your user@host hostmask that + description = lib.mdDoc '' + User name. Part of your `user@host` hostmask that appears to other on IRC. ''; }; @@ -158,7 +160,7 @@ let type = listOf str; default = [ ]; example = [ "irc.oftc.net" ]; - description = "IRC Server Address List."; + description = lib.mdDoc "IRC Server Address List."; }; }; }; @@ -219,7 +221,7 @@ in { meta.maintainers = with maintainers; [ thiagokokada ]; options.programs.hexchat = with types; { - enable = mkEnableOption "HexChat, a graphical IRC client"; + enable = mkEnableOption (lib.mdDoc "HexChat, a graphical IRC client"); channels = mkOption { type = attrsOf modChannelOption; @@ -254,8 +256,8 @@ in { userName = "my_username"; }; }''; - description = '' - Configures $XDG_CONFIG_HOME/hexchat/servlist.conf. + description = lib.mdDoc '' + Configures {file}`$XDG_CONFIG_HOME/hexchat/servlist.conf`. ''; }; @@ -270,9 +272,9 @@ in { text_font = "Monospace 14"; }; ''; - description = '' - Configuration for $XDG_CONFIG_HOME/hexchat/hexchat.conf, see - + description = lib.mdDoc '' + Configuration for {file}`$XDG_CONFIG_HOME/hexchat/hexchat.conf`, see + for supported values. ''; }; @@ -307,9 +309,9 @@ in { stripRoot = false; }; ''; - description = '' + description = lib.mdDoc '' Theme package for HexChat. Expects a derivation containing decompressed - theme files. Note, .hct files are actually ZIP files, + theme files. Note, `.hct` files are actually ZIP files, as seen in example. ''; }; diff --git a/modules/programs/himalaya.nix b/modules/programs/himalaya.nix index a2b6cd0f..fb0dbde3 100644 --- a/modules/programs/himalaya.nix +++ b/modules/programs/himalaya.nix @@ -118,21 +118,22 @@ in { options = { programs.himalaya = { - enable = lib.mkEnableOption "the Himalaya email client"; + enable = lib.mkEnableOption (lib.mdDoc "the Himalaya email client"); package = lib.mkPackageOptionMD pkgs "himalaya" { }; settings = lib.mkOption { type = lib.types.submodule { freeformType = tomlFormat.type; }; default = { }; - description = '' + description = lib.mdDoc '' Himalaya global configuration. - See for supported values. + See for supported values. ''; }; }; services = { himalaya-notify = { - enable = lib.mkEnableOption "the Himalaya new emails notifier service"; + enable = lib.mkEnableOption + (lib.mdDoc "the Himalaya new emails notifier service"); environment = lib.mkOption { type = with lib.types; attrsOf str; @@ -142,7 +143,7 @@ in { "PASSWORD_STORE_DIR" = "~/.password-store"; } ''; - description = '' + description = lib.mdDoc '' Extra environment variables to be exported in the service. ''; }; @@ -152,7 +153,7 @@ in { type = with lib.types; nullOr str; default = null; example = "gmail"; - description = '' + description = lib.mdDoc '' Name of the account the notifier should be started for. If no account is given, the default one is used. ''; @@ -162,7 +163,7 @@ in { type = with lib.types; nullOr int; default = null; example = "500"; - description = '' + description = lib.mdDoc '' Notifier lifetime of the IDLE session (in seconds). ''; }; @@ -170,8 +171,8 @@ in { }; himalaya-watch = { - enable = - lib.mkEnableOption "the Himalaya folder changes watcher service"; + enable = lib.mkEnableOption + (lib.mdDoc "the Himalaya folder changes watcher service"); environment = lib.mkOption { type = with lib.types; attrsOf str; @@ -181,7 +182,7 @@ in { "PASSWORD_STORE_DIR" = "~/.password-store"; } ''; - description = '' + description = lib.mdDoc '' Extra environment variables to be exported in the service. ''; }; @@ -191,7 +192,7 @@ in { type = with lib.types; nullOr str; default = null; example = "gmail"; - description = '' + description = lib.mdDoc '' Name of the account the watcher should be started for. If no account is given, the default one is used. ''; @@ -201,7 +202,7 @@ in { type = with lib.types; nullOr int; default = null; example = "500"; - description = '' + description = lib.mdDoc '' Watcher lifetime of the IDLE session (in seconds). ''; }; @@ -212,7 +213,8 @@ in { accounts.email.accounts = lib.mkOption { type = lib.types.attrsOf (lib.types.submodule { options.himalaya = { - enable = lib.mkEnableOption "Himalaya for this email account"; + enable = + lib.mkEnableOption (lib.mdDoc "Himalaya for this email account"); # TODO: remove me for the next release backend = lib.mkOption { @@ -236,9 +238,9 @@ in { settings = lib.mkOption { type = lib.types.submodule { freeformType = tomlFormat.type; }; default = { }; - description = '' + description = lib.mdDoc '' Himalaya configuration for this email account. - See for supported values. + See for supported values. ''; }; }; diff --git a/modules/programs/home-manager.nix b/modules/programs/home-manager.nix index b5a73298..717d02c1 100644 --- a/modules/programs/home-manager.nix +++ b/modules/programs/home-manager.nix @@ -11,17 +11,17 @@ in { options = { programs.home-manager = { - enable = mkEnableOption "Home Manager"; + enable = mkEnableOption (lib.mdDoc "Home Manager"); path = mkOption { type = types.nullOr types.str; default = null; example = "$HOME/devel/home-manager"; - description = '' + description = lib.mdDoc '' The default path to use for Home Manager. When - null, then the home-manager - channel, $HOME/.config/nixpkgs/home-manager, and - $HOME/.nixpkgs/home-manager will be attempted. + `null`, then the {file}`home-manager` + channel, {file}`$HOME/.config/nixpkgs/home-manager`, and + {file}`$HOME/.nixpkgs/home-manager` will be attempted. ''; }; }; diff --git a/modules/programs/hstr.nix b/modules/programs/hstr.nix index be247a60..cb580f7b 100644 --- a/modules/programs/hstr.nix +++ b/modules/programs/hstr.nix @@ -10,17 +10,17 @@ in { meta.maintainers = [ hm.maintainers.Dines97 ]; options.programs.hstr = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Bash And Zsh shell history suggest box - easily view, navigate, search and - manage your command history''; + manage your command history''); package = mkPackageOptionMD pkgs "hstr" { }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = true; }; }; diff --git a/modules/programs/htop.nix b/modules/programs/htop.nix index 27368602..0b1773ea 100644 --- a/modules/programs/htop.nix +++ b/modules/programs/htop.nix @@ -110,7 +110,7 @@ in { meta.maintainers = [ hm.maintainers.bjpbakker ]; options.programs.htop = { - enable = mkEnableOption "htop"; + enable = mkEnableOption (lib.mdDoc "htop"); settings = mkOption { type = types.attrs; @@ -149,9 +149,9 @@ in { (text "Systemd") ]); ''; - description = '' + description = lib.mdDoc '' Configuration options to add to - $XDG_CONFIG_HOME/htop/htoprc. + {file}`$XDG_CONFIG_HOME/htop/htoprc`. ''; }; @@ -159,7 +159,7 @@ in { type = types.package; default = pkgs.htop; defaultText = literalExpression "pkgs.htop"; - description = "Package containing the htop program."; + description = lib.mdDoc "Package containing the {command}`htop` program."; }; }; diff --git a/modules/programs/hyfetch.nix b/modules/programs/hyfetch.nix index 726bc94e..a8d63b9a 100644 --- a/modules/programs/hyfetch.nix +++ b/modules/programs/hyfetch.nix @@ -10,13 +10,13 @@ in { meta.maintainers = [ maintainers.lilyinstarlight ]; options.programs.hyfetch = { - enable = mkEnableOption "hyfetch"; + enable = mkEnableOption (lib.mdDoc "hyfetch"); package = mkOption { type = types.package; default = pkgs.hyfetch; defaultText = literalExpression "pkgs.hyfetch"; - description = "The hyfetch package to use."; + description = lib.mdDoc "The hyfetch package to use."; }; settings = mkOption { @@ -31,7 +31,7 @@ in { }; } ''; - description = "JSON config for HyFetch"; + description = lib.mdDoc "JSON config for HyFetch"; }; }; diff --git a/modules/programs/i3status-rust.nix b/modules/programs/i3status-rust.nix index 39146d55..b729f147 100644 --- a/modules/programs/i3status-rust.nix +++ b/modules/programs/i3status-rust.nix @@ -12,7 +12,8 @@ in { meta.maintainers = with lib.maintainers; [ farlion thiagokokada ]; options.programs.i3status-rust = { - enable = mkEnableOption "a replacement for i3-status written in Rust"; + enable = + mkEnableOption (lib.mdDoc "a replacement for i3-status written in Rust"); bars = mkOption { type = types.attrsOf (types.submodule { @@ -49,10 +50,10 @@ in { format = " $timestamp.datetime(f:'%a %d/%m %R') "; } ]; - description = '' + description = lib.mdDoc '' Configuration blocks to add to i3status-rust - config. See - + {file}`config`. See + for block options. ''; example = literalExpression '' @@ -86,9 +87,9 @@ in { settings = mkOption { type = settingsFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Any extra options to add to i3status-rust - config. + {file}`config`. ''; example = literalExpression '' { @@ -106,9 +107,9 @@ in { icons = mkOption { type = types.str; default = "none"; - description = '' + description = lib.mdDoc '' The icons set to use. See - + for a list of available icon sets. ''; example = "awesome6"; @@ -117,9 +118,9 @@ in { theme = mkOption { type = types.str; default = "plain"; - description = '' + description = lib.mdDoc '' The theme to use. See - + for a list of available themes. ''; example = "gruvbox-dark"; @@ -161,20 +162,17 @@ in { ]; }; }; - description = '' + description = lib.mdDoc '' Attribute set of i3status-rust bars, each with their own configuration. - Each bar name generates a config file suffixed with - the bar's name from the attribute set, like so: - config-''${name}.toml. - + Each bar {var}`name` generates a config file suffixed with + the bar's {var}`name` from the attribute set, like so: + {file}`config-''${name}.toml`. + This way, multiple config files can be generated, such as for having a top and a bottom bar. - + See - - i3status-rust - 1 - + {manpage}`i3status-rust(1)` for options. ''; example = literalExpression '' @@ -228,7 +226,7 @@ in { type = types.package; default = pkgs.i3status-rust; defaultText = literalExpression "pkgs.i3status-rust"; - description = "Package providing i3status-rust"; + description = lib.mdDoc "Package providing i3status-rust"; }; }; diff --git a/modules/programs/i3status.nix b/modules/programs/i3status.nix index f3006f2c..34f8d1c0 100644 --- a/modules/programs/i3status.nix +++ b/modules/programs/i3status.nix @@ -36,12 +36,12 @@ in { meta.maintainers = [ hm.maintainers.justinlovinger ]; options.programs.i3status = { - enable = mkEnableOption "i3status"; + enable = mkEnableOption (lib.mdDoc "i3status"); enableDefault = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether or not to enable the default configuration. ''; @@ -50,14 +50,11 @@ in { general = mkOption { type = settingsType; default = { }; - description = '' - Configuration to add to i3status config - general section. + description = lib.mdDoc '' + Configuration to add to i3status {file}`config` + `general` section. See - - i3status - 1 - + {manpage}`i3status(1)` for options. ''; example = literalExpression '' @@ -77,26 +74,23 @@ in { enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether or not to enable this module. ''; }; position = mkOption { type = with types; either int float; - description = '' - Position of this module in i3status order. + description = lib.mdDoc '' + Position of this module in i3status `order`. ''; }; settings = mkOption { type = settingsType; default = { }; - description = '' + description = lib.mdDoc '' Configuration to add to this i3status module. See - - i3status - 1 - + {manpage}`i3status(1)` for options. ''; example = literalExpression '' @@ -110,13 +104,10 @@ in { }; }); default = { }; - description = '' - Modules to add to i3status config file. + description = lib.mdDoc '' + Modules to add to i3status {file}`config` file. See - - i3status - 1 - + {manpage}`i3status(1)` for options. ''; example = literalExpression '' diff --git a/modules/programs/imv.nix b/modules/programs/imv.nix index 348c4b2e..96c22e25 100644 --- a/modules/programs/imv.nix +++ b/modules/programs/imv.nix @@ -13,20 +13,17 @@ in { meta.maintainers = [ maintainers.christoph-heiss ]; options.programs.imv = { - enable = mkEnableOption - "imv: a command line image viewer intended for use with tiling window managers"; + enable = mkEnableOption (lib.mdDoc + "imv: a command line image viewer intended for use with tiling window managers"); package = mkPackageOptionMD pkgs "imv" { }; settings = mkOption { default = { }; type = with types; attrsOf (attrsOf (oneOf [ bool int str ])); - description = '' + description = lib.mdDoc '' Configuration options for imv. See - - imv - 5 - . + {manpage}`imv(5)`. ''; example = literalExpression '' { diff --git a/modules/programs/info.nix b/modules/programs/info.nix index a7d2692b..79aabc90 100644 --- a/modules/programs/info.nix +++ b/modules/programs/info.nix @@ -38,7 +38,7 @@ in { '') ]; - options.programs.info.enable = mkEnableOption "GNU Info"; + options.programs.info.enable = mkEnableOption (lib.mdDoc "GNU Info"); config = mkIf cfg.enable { home.packages = [ diff --git a/modules/programs/ion.nix b/modules/programs/ion.nix index 0bda85c0..328e643a 100644 --- a/modules/programs/ion.nix +++ b/modules/programs/ion.nix @@ -12,13 +12,14 @@ in { meta.maintainers = [ maintainers.jo1gi ]; options.programs.ion = { - enable = mkEnableOption "the Ion Shell. Compatible with Redox and Linux"; + enable = mkEnableOption + (lib.mdDoc "the Ion Shell. Compatible with Redox and Linux"); package = mkOption { type = types.package; default = pkgs.ion; defaultText = literalExpression "pkgs.ion"; - description = '' + description = lib.mdDoc '' The ion package to install. May be used to change the version. ''; }; @@ -26,7 +27,7 @@ in { initExtra = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Ion script which is called during ion initialization. ''; }; @@ -39,7 +40,7 @@ in { g = "git"; } ''; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. ''; diff --git a/modules/programs/irssi.nix b/modules/programs/irssi.nix index d0953ed7..5faa84cb 100644 --- a/modules/programs/irssi.nix +++ b/modules/programs/irssi.nix @@ -64,13 +64,13 @@ let type = types.nullOr types.str; visible = false; default = null; - description = "Name of the channel."; + description = lib.mdDoc "Name of the channel."; }; autoJoin = mkOption { type = types.bool; default = false; - description = "Whether to join this channel on connect."; + description = lib.mdDoc "Whether to join this channel on connect."; }; }; }; @@ -85,50 +85,51 @@ let nick = mkOption { type = types.str; - description = "Nickname in that network."; + description = lib.mdDoc "Nickname in that network."; }; type = mkOption { type = types.str; - description = "Type of the network."; + description = lib.mdDoc "Type of the network."; default = "IRC"; }; autoCommands = mkOption { type = types.listOf types.str; default = [ ]; - description = "List of commands to execute on connect."; + description = lib.mdDoc "List of commands to execute on connect."; }; server = { address = mkOption { type = types.str; - description = "Address of the chat server."; + description = lib.mdDoc "Address of the chat server."; }; port = mkOption { type = types.port; default = 6667; - description = "Port of the chat server."; + description = lib.mdDoc "Port of the chat server."; }; ssl = { enable = mkOption { type = types.bool; default = true; - description = "Whether SSL should be used."; + description = lib.mdDoc "Whether SSL should be used."; }; verify = mkOption { type = types.bool; default = true; - description = "Whether the SSL certificate should be verified."; + description = + lib.mdDoc "Whether the SSL certificate should be verified."; }; certificateFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Path to a file containing the certificate used for client authentication to the server. ''; @@ -138,12 +139,13 @@ let autoConnect = mkOption { type = types.bool; default = false; - description = "Whether Irssi connects to the server on launch."; + description = + lib.mdDoc "Whether Irssi connects to the server on launch."; }; }; channels = mkOption { - description = "Channels for the given network."; + description = lib.mdDoc "Channels for the given network."; type = types.attrsOf channelType; default = { }; }; @@ -151,9 +153,9 @@ let saslExternal = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable SASL external authentication. This requires setting a path in - . + [](#opt-programs.irssi.networks._name_.server.ssl.certificateFile). ''; }; }; @@ -163,11 +165,12 @@ in { options = { programs.irssi = { - enable = mkEnableOption "the Irssi chat client"; + enable = mkEnableOption (lib.mdDoc "the Irssi chat client"); extraConfig = mkOption { default = ""; - description = "These lines are appended to the Irssi configuration."; + description = + lib.mdDoc "These lines are appended to the Irssi configuration."; type = types.lines; }; @@ -177,7 +180,8 @@ in { J = "join"; BYE = "quit"; }; - description = "An attribute set that maps aliases to commands."; + description = + lib.mdDoc "An attribute set that maps aliases to commands."; type = types.attrsOf types.str; }; @@ -198,7 +202,7 @@ in { }; } ''; - description = "An attribute set of chat networks."; + description = lib.mdDoc "An attribute set of chat networks."; type = types.attrsOf networkType; }; }; diff --git a/modules/programs/java.nix b/modules/programs/java.nix index d2c9c96b..22755dd3 100644 --- a/modules/programs/java.nix +++ b/modules/programs/java.nix @@ -25,9 +25,9 @@ in { type = types.package; default = pkgs.jdk; defaultText = "pkgs.jdk"; - description = '' + description = lib.mdDoc '' Java package to install. Typical values are - pkgs.jdk or pkgs.jre. + `pkgs.jdk` or `pkgs.jre`. ''; }; }; diff --git a/modules/programs/joshuto.nix b/modules/programs/joshuto.nix index 63c32523..82132db5 100644 --- a/modules/programs/joshuto.nix +++ b/modules/programs/joshuto.nix @@ -9,23 +9,23 @@ in { meta.maintainers = [ hm.maintainers.rasmus-kirk ]; options.programs.joshuto = { - enable = mkEnableOption "joshuto file manager"; + enable = mkEnableOption (lib.mdDoc "joshuto file manager"); package = mkOption { type = types.package; default = pkgs.joshuto; defaultText = literalExpression "pkgs.joshuto"; - description = "The package to use for joshuto."; + description = lib.mdDoc "The package to use for joshuto."; }; settings = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/joshuto/joshuto.toml. - - See + {file}`$XDG_CONFIG_HOME/joshuto/joshuto.toml`. + + See for the full list of options. ''; }; @@ -33,11 +33,11 @@ in { keymap = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/joshuto/keymap.toml. - - See + {file}`$XDG_CONFIG_HOME/joshuto/keymap.toml`. + + See for the full list of options. Note that this option will overwrite any existing keybinds. ''; }; @@ -45,11 +45,11 @@ in { mimetype = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/joshuto/mimetype.toml. - - See + {file}`$XDG_CONFIG_HOME/joshuto/mimetype.toml`. + + See for the full list of options ''; }; @@ -57,11 +57,11 @@ in { theme = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/joshuto/theme.toml. - - See + {file}`$XDG_CONFIG_HOME/joshuto/theme.toml`. + + See for the full list of options ''; }; diff --git a/modules/programs/jq.nix b/modules/programs/jq.nix index 78ad57f5..b7683219 100644 --- a/modules/programs/jq.nix +++ b/modules/programs/jq.nix @@ -8,7 +8,7 @@ let colorType = mkOption { type = types.str; - description = "ANSI color definition"; + description = lib.mdDoc "ANSI color definition"; example = "1;31"; visible = false; }; @@ -28,13 +28,13 @@ let in { options = { programs.jq = { - enable = mkEnableOption "the jq command-line JSON processor"; + enable = mkEnableOption (lib.mdDoc "the jq command-line JSON processor"); package = mkOption { type = types.package; default = pkgs.jq; defaultText = literalExpression "pkgs.jq"; - description = "jq package to use."; + description = lib.mdDoc "jq package to use."; }; colors = mkOption { diff --git a/modules/programs/jujutsu.nix b/modules/programs/jujutsu.nix index 9c0ad6a1..39406ef5 100644 --- a/modules/programs/jujutsu.nix +++ b/modules/programs/jujutsu.nix @@ -11,8 +11,8 @@ in { meta.maintainers = [ maintainers.shikanime ]; options.programs.jujutsu = { - enable = - mkEnableOption "a Git-compatible DVCS that is both simple and powerful"; + enable = mkEnableOption + (lib.mdDoc "a Git-compatible DVCS that is both simple and powerful"); package = mkPackageOptionMD pkgs "jujutsu" { }; @@ -27,9 +27,9 @@ in { }; } ''; - description = '' - Options to add to the .jjconfig.toml file. See - + description = lib.mdDoc '' + Options to add to the {file}`.jjconfig.toml` file. See + for options. ''; }; @@ -37,19 +37,19 @@ in { enableBashIntegration = mkOption { type = types.bool; default = true; - description = "Whether to enable Bash integration."; + description = lib.mdDoc "Whether to enable Bash integration."; }; enableZshIntegration = mkOption { type = types.bool; default = true; - description = "Whether to enable Zsh integration."; + description = lib.mdDoc "Whether to enable Zsh integration."; }; enableFishIntegration = mkOption { type = types.bool; default = true; - description = "Whether to enable Fish integration."; + description = lib.mdDoc "Whether to enable Fish integration."; }; }; diff --git a/modules/programs/k9s.nix b/modules/programs/k9s.nix index f0d1a99e..114e8a1f 100644 --- a/modules/programs/k9s.nix +++ b/modules/programs/k9s.nix @@ -11,18 +11,18 @@ in { meta.maintainers = [ hm.maintainers.katexochen ]; options.programs.k9s = { - enable = - mkEnableOption "k9s - Kubernetes CLI To Manage Your Clusters In Style"; + enable = mkEnableOption + (lib.mdDoc "k9s - Kubernetes CLI To Manage Your Clusters In Style"); package = mkPackageOptionMD pkgs "k9s" { }; settings = mkOption { type = yamlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/k9s/config.yml. See - + {file}`$XDG_CONFIG_HOME/k9s/config.yml`. See + for supported values. ''; example = literalExpression '' @@ -35,10 +35,10 @@ in { skin = mkOption { type = yamlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Skin written to - $XDG_CONFIG_HOME/k9s/skin.yml. See - + {file}`$XDG_CONFIG_HOME/k9s/skin.yml`. See + for supported values. ''; example = literalExpression '' diff --git a/modules/programs/kakoune.nix b/modules/programs/kakoune.nix index c963d2be..77503dc0 100644 --- a/modules/programs/kakoune.nix +++ b/modules/programs/kakoune.nix @@ -51,16 +51,16 @@ let "User" ]; example = "SetOption"; - description = '' + description = lib.mdDoc '' The name of the hook. For a description, see - . + . ''; }; once = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Remove the hook after running it once. ''; }; @@ -68,7 +68,7 @@ let group = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Add the hook to the named group. ''; }; @@ -77,7 +77,7 @@ let type = types.nullOr types.str; default = null; example = "filetype=latex"; - description = '' + description = lib.mdDoc '' Additional option to pass to the hook. ''; }; @@ -86,7 +86,7 @@ let type = types.lines; default = ""; example = "set-option window indentwidth 2"; - description = '' + description = lib.mdDoc '' Commands to run when the hook is activated. ''; }; @@ -98,7 +98,7 @@ let mode = mkOption { type = types.str; example = "user"; - description = '' + description = lib.mdDoc '' The mode in which the mapping takes effect. ''; }; @@ -106,7 +106,7 @@ let docstring = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Optional documentation text to display in info boxes. ''; }; @@ -114,9 +114,9 @@ let key = mkOption { type = types.str; example = ""; - description = '' + description = lib.mdDoc '' The key to be mapped. See - + for possible values. ''; }; @@ -124,7 +124,7 @@ let effect = mkOption { type = types.str; example = ":wq"; - description = '' + description = lib.mdDoc '' The sequence of keys to be mapped. ''; }; @@ -136,35 +136,35 @@ let colorScheme = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Set the color scheme. To see available schemes, enter - colorscheme at the kakoune prompt. + {command}`colorscheme` at the kakoune prompt. ''; }; tabStop = mkOption { type = types.nullOr types.ints.unsigned; default = null; - description = '' + description = lib.mdDoc '' The width of a tab in spaces. The kakoune default is - 6. + `6`. ''; }; indentWidth = mkOption { type = types.nullOr types.ints.unsigned; default = null; - description = '' + description = lib.mdDoc '' The width of an indentation in spaces. - The kakoune default is 4. - If 0, a tab will be used instead. + The kakoune default is `4`. + If `0`, a tab will be used instead. ''; }; incrementalSearch = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Execute a search as it is being typed. ''; }; @@ -172,7 +172,7 @@ let alignWithTabs = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Use tabs for the align command. ''; }; @@ -182,27 +182,27 @@ let (types.listOf (types.enum [ "command" "onkey" "normal" ])); default = null; example = [ "command" "normal" ]; - description = '' + description = lib.mdDoc '' Contexts in which to display automatic information box. - The kakoune default is [ "command" "onkey" ]. + The kakoune default is `[ "command" "onkey" ]`. ''; }; autoComplete = mkOption { type = types.nullOr (types.listOf (types.enum [ "insert" "prompt" ])); default = null; - description = '' + description = lib.mdDoc '' Modes in which to display possible completions. - The kakoune default is [ "insert" "prompt" ]. + The kakoune default is `[ "insert" "prompt" ]`. ''; }; autoReload = mkOption { type = types.nullOr (types.enum [ "yes" "no" "ask" ]); default = null; - description = '' + description = lib.mdDoc '' Reload buffers when an external modification is detected. - The kakoune default is "ask". + The kakoune default is `"ask"`. ''; }; @@ -212,7 +212,7 @@ let lines = mkOption { type = types.ints.unsigned; default = 0; - description = '' + description = lib.mdDoc '' The number of lines to keep visible around the cursor. ''; }; @@ -220,14 +220,14 @@ let columns = mkOption { type = types.ints.unsigned; default = 0; - description = '' + description = lib.mdDoc '' The number of columns to keep visible around the cursor. ''; }; }; }); default = null; - description = '' + description = lib.mdDoc '' How many lines and columns to keep visible around the cursor. ''; }; @@ -238,7 +238,7 @@ let setTitle = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Change the title of the terminal emulator. ''; }; @@ -246,7 +246,7 @@ let statusLine = mkOption { type = types.enum [ "top" "bottom" ]; default = "bottom"; - description = '' + description = lib.mdDoc '' Where to display the status line. ''; }; @@ -254,7 +254,7 @@ let assistant = mkOption { type = types.enum [ "clippy" "cat" "dilbert" "none" ]; default = "clippy"; - description = '' + description = lib.mdDoc '' The assistant displayed in info boxes. ''; }; @@ -262,7 +262,7 @@ let enableMouse = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable mouse support. ''; }; @@ -270,7 +270,7 @@ let changeColors = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Change color palette. ''; }; @@ -278,7 +278,7 @@ let wheelDownButton = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Button to send for wheel down events. ''; }; @@ -286,7 +286,7 @@ let wheelUpButton = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Button to send for wheel up events. ''; }; @@ -294,24 +294,24 @@ let shiftFunctionKeys = mkOption { type = types.nullOr types.ints.unsigned; default = null; - description = '' + description = lib.mdDoc '' Amount by which shifted function keys are offset. That is, if the terminal sends F13 for Shift-F1, this - should be 12. + should be `12`. ''; }; useBuiltinKeyParser = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Bypass ncurses key parser and use an internal one. ''; }; }; }); default = null; - description = '' + description = lib.mdDoc '' Settings for the ncurses interface. ''; }; @@ -319,9 +319,9 @@ let showMatching = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Highlight the matching char of the character under the - selections' cursor using the MatchingChar + selections' cursor using the `MatchingChar` face. ''; }; @@ -329,12 +329,12 @@ let wrapLines = mkOption { type = types.nullOr (types.submodule { options = { - enable = mkEnableOption "the wrap lines highlighter"; + enable = mkEnableOption (lib.mdDoc "the wrap lines highlighter"); word = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Wrap at word boundaries instead of codepoint boundaries. ''; }; @@ -342,7 +342,7 @@ let indent = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Preserve line indentation when wrapping. ''; }; @@ -350,7 +350,7 @@ let maxWidth = mkOption { type = types.nullOr types.ints.unsigned; default = null; - description = '' + description = lib.mdDoc '' Wrap text at maxWidth, even if the window is wider. ''; }; @@ -359,16 +359,16 @@ let type = types.nullOr types.str; default = null; example = "⏎"; - description = '' + description = lib.mdDoc '' Prefix wrapped lines with marker text. - If not null, + If not `null`, the marker text will be displayed in the indentation if possible. ''; }; }; }); default = null; - description = '' + description = lib.mdDoc '' Settings for the wrap lines highlighter. ''; }; @@ -376,12 +376,12 @@ let numberLines = mkOption { type = types.nullOr (types.submodule { options = { - enable = mkEnableOption "the number lines highlighter"; + enable = mkEnableOption (lib.mdDoc "the number lines highlighter"); relative = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Show line numbers relative to the main cursor line. ''; }; @@ -389,7 +389,7 @@ let highlightCursor = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Highlight the cursor line with a separate face. ''; }; @@ -397,16 +397,16 @@ let separator = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' String that separates the line number column from the buffer contents. The kakoune default is - "|". + `"|"`. ''; }; }; }); default = null; - description = '' + description = lib.mdDoc '' Settings for the number lines highlighter. ''; }; @@ -414,56 +414,57 @@ let showWhitespace = mkOption { type = types.nullOr (types.submodule { options = { - enable = mkEnableOption "the show whitespace highlighter"; + enable = + mkEnableOption (lib.mdDoc "the show whitespace highlighter"); lineFeed = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The character to display for line feeds. - The kakoune default is "¬". + The kakoune default is `"¬"`. ''; }; space = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The character to display for spaces. - The kakoune default is "·". + The kakoune default is `"·"`. ''; }; nonBreakingSpace = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The character to display for non-breaking spaces. - The kakoune default is "⍽". + The kakoune default is `"⍽"`. ''; }; tab = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The character to display for tabs. - The kakoune default is "→". + The kakoune default is `"→"`. ''; }; tabStop = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The character to append to tabs to reach the width of a tabstop. - The kakoune default is " ". + The kakoune default is `" "`. ''; }; }; }); default = null; - description = '' + description = lib.mdDoc '' Settings for the show whitespaces highlighter. ''; }; @@ -471,18 +472,18 @@ let keyMappings = mkOption { type = types.listOf keyMapping; default = [ ]; - description = '' + description = lib.mdDoc '' User-defined key mappings. For documentation, see - . + . ''; }; hooks = mkOption { type = types.listOf hook; default = [ ]; - description = '' + description = lib.mdDoc '' Global hooks. For documentation, see - . + . ''; }; }; @@ -620,31 +621,31 @@ let in { options = { programs.kakoune = { - enable = mkEnableOption "the kakoune text editor"; + enable = mkEnableOption (lib.mdDoc "the kakoune text editor"); package = mkPackageOptionMD pkgs "kakoune-unwrapped" { }; config = mkOption { type = types.nullOr configModule; default = { }; - description = "kakoune configuration options."; + description = lib.mdDoc "kakoune configuration options."; }; defaultEditor = mkOption { type = types.bool; default = false; - description = '' - Whether to configure kak as the default - editor using the EDITOR environment variable. + description = lib.mdDoc '' + Whether to configure {command}`kak` as the default + editor using the {env}`EDITOR` environment variable. ''; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration lines to add to - $XDG_CONFIG_HOME/kak/kakrc. + {file}`$XDG_CONFIG_HOME/kak/kakrc`. ''; }; @@ -652,10 +653,10 @@ in { type = with types; listOf package; default = [ ]; example = literalExpression "[ pkgs.kakounePlugins.kak-fzf ]"; - description = '' + description = lib.mdDoc '' List of kakoune plugins to install. To get a list of supported plugins run: - nix-env -f '<nixpkgs>' -qaP -A kakounePlugins. + {command}`nix-env -f '' -qaP -A kakounePlugins`. ''; }; }; diff --git a/modules/programs/keychain.nix b/modules/programs/keychain.nix index 3eadf72c..74a53c9b 100644 --- a/modules/programs/keychain.nix +++ b/modules/programs/keychain.nix @@ -19,13 +19,13 @@ in { meta.maintainers = [ ]; options.programs.keychain = { - enable = mkEnableOption "keychain"; + enable = mkEnableOption (lib.mdDoc "keychain"); package = mkOption { type = types.package; default = pkgs.keychain; defaultText = literalExpression "pkgs.keychain"; - description = '' + description = lib.mdDoc '' Keychain package to install. ''; }; @@ -33,7 +33,7 @@ in { keys = mkOption { type = types.listOf types.str; default = [ "id_rsa" ]; - description = '' + description = lib.mdDoc '' Keys to add to keychain. ''; }; @@ -41,7 +41,7 @@ in { agents = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' Agents to add. ''; }; @@ -50,7 +50,7 @@ in { type = types.nullOr (types.enum [ "local" "any" "local-once" "any-once" ]); default = null; - description = '' + description = lib.mdDoc '' Inherit type to attempt from agent variables from the environment. ''; }; @@ -58,7 +58,7 @@ in { extraFlags = mkOption { type = types.listOf types.str; default = [ "--quiet" ]; - description = '' + description = lib.mdDoc '' Extra flags to pass to keychain. ''; }; @@ -66,7 +66,7 @@ in { enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -74,7 +74,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; @@ -82,7 +82,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -90,7 +90,7 @@ in { enableNushellIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Nushell integration. ''; }; @@ -99,8 +99,8 @@ in { default = true; type = types.bool; visible = pkgs.stdenv.hostPlatform.isLinux; - description = '' - Whether to run keychain from your ~/.xsession. + description = lib.mdDoc '' + Whether to run keychain from your {file}`~/.xsession`. ''; }; }; diff --git a/modules/programs/khal-accounts.nix b/modules/programs/khal-accounts.nix index ad94adc9..dde7fb19 100644 --- a/modules/programs/khal-accounts.nix +++ b/modules/programs/khal-accounts.nix @@ -4,12 +4,12 @@ with lib; { options.khal = { - enable = lib.mkEnableOption "khal access"; + enable = lib.mkEnableOption (lib.mdDoc "khal access"); readOnly = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Keep khal from making any changes to this account. ''; }; diff --git a/modules/programs/khal-calendar-accounts.nix b/modules/programs/khal-calendar-accounts.nix index 6910d627..e10a8fd5 100644 --- a/modules/programs/khal-calendar-accounts.nix +++ b/modules/programs/khal-calendar-accounts.nix @@ -7,7 +7,7 @@ with lib; type = mkOption { type = types.nullOr (types.enum [ "calendar" "discover" ]); default = null; - description = '' + description = lib.mdDoc '' Either a single calendar (calendar which is the default) or a directory with multiple calendars (discover). ''; }; @@ -15,7 +15,7 @@ with lib; glob = mkOption { type = types.str; default = "*"; - description = '' + description = lib.mdDoc '' The glob expansion to be searched for events or birthdays when type is set to discover. ''; @@ -41,7 +41,7 @@ with lib; "light red" ]); default = null; - description = '' + description = lib.mdDoc '' Color in which events in this calendar are displayed. ''; example = "light green"; @@ -50,7 +50,7 @@ with lib; priority = mkOption { type = types.int; default = 10; - description = '' + description = lib.mdDoc '' Priority of a calendar used for coloring. ''; }; diff --git a/modules/programs/kitty.nix b/modules/programs/kitty.nix index 698e8034..fe63cb32 100644 --- a/modules/programs/kitty.nix +++ b/modules/programs/kitty.nix @@ -55,13 +55,13 @@ let }; in { options.programs.kitty = { - enable = mkEnableOption "Kitty terminal emulator"; + enable = mkEnableOption (lib.mdDoc "Kitty terminal emulator"); package = mkOption { type = types.package; default = pkgs.kitty; defaultText = literalExpression "pkgs.kitty"; - description = '' + description = lib.mdDoc '' Kitty package to install. ''; }; @@ -69,7 +69,8 @@ in { darwinLaunchOptions = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = "Command-line options to use when launched by Mac OS GUI"; + description = + lib.mdDoc "Command-line options to use when launched by Mac OS GUI"; example = literalExpression '' [ "--single-instance" @@ -89,10 +90,10 @@ in { update_check_interval = 0; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/kitty/kitty.conf. See - + {file}`$XDG_CONFIG_HOME/kitty/kitty.conf`. See + for the documentation. ''; }; @@ -100,10 +101,10 @@ in { theme = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Apply a Kitty color theme. This option takes the friendly name of - any theme given by the command kitty +kitten themes. - See + any theme given by the command {command}`kitty +kitten themes`. + See for more details. ''; example = "Space Gray Eighties"; @@ -112,13 +113,13 @@ in { font = mkOption { type = types.nullOr hm.types.fontType; default = null; - description = "The font to use."; + description = lib.mdDoc "The font to use."; }; keybindings = mkOption { type = types.attrsOf types.str; default = { }; - description = "Mapping of keybindings to actions."; + description = lib.mdDoc "Mapping of keybindings to actions."; example = literalExpression '' { "ctrl+c" = "copy_or_interrupt"; @@ -130,7 +131,7 @@ in { environment = mkOption { type = types.attrsOf types.str; default = { }; - description = "Environment variables to set or override."; + description = lib.mdDoc "Environment variables to set or override."; example = literalExpression '' { "LS_COLORS" = "1"; @@ -143,29 +144,32 @@ in { type = types.str; default = "enabled"; example = "no-cursor"; - description = '' + description = lib.mdDoc '' Set the mode of the shell integration. This accepts the same options - as the shell_integration option of Kitty. Note that - no-rc is always implied. See - + as the `shell_integration` option of Kitty. Note that + `no-rc` is always implied. See + for more details. ''; }; - enableBashIntegration = mkEnableOption "Kitty Bash integration" + enableBashIntegration = + mkEnableOption (lib.mdDoc "Kitty Bash integration") // shellIntegrationDefaultOpt; - enableFishIntegration = mkEnableOption "Kitty fish integration" + enableFishIntegration = + mkEnableOption (lib.mdDoc "Kitty fish integration") // shellIntegrationDefaultOpt; - enableZshIntegration = mkEnableOption "Kitty Z Shell integration" + enableZshIntegration = + mkEnableOption (lib.mdDoc "Kitty Z Shell integration") // shellIntegrationDefaultOpt; }; extraConfig = mkOption { default = ""; type = types.lines; - description = "Additional configuration to add."; + description = lib.mdDoc "Additional configuration to add."; }; }; diff --git a/modules/programs/kodi.nix b/modules/programs/kodi.nix index bae862ae..91bd3448 100644 --- a/modules/programs/kodi.nix +++ b/modules/programs/kodi.nix @@ -125,7 +125,7 @@ in { meta.maintainers = [ hm.maintainers.dwagenk ]; options.programs.kodi = { - enable = mkEnableOption "Kodi"; + enable = mkEnableOption (lib.mdDoc "Kodi"); package = mkOption { type = types.package; @@ -133,8 +133,8 @@ in { defaultText = literalExpression "pkgs.kodi"; example = literalExpression "pkgs.kodi.withPackages (exts: [ exts.pvr-iptvsimple ])"; - description = '' - The kodi package to use. + description = lib.mdDoc '' + The `kodi` package to use. Can be used to specify extensions. ''; }; @@ -145,7 +145,7 @@ in { defaultText = literalExpression ''"''${config.home.homeDirectory}/.kodi"''; example = literalExpression ''"''${config.xdg.dataHome}/kodi"''; - description = "Directory to store configuration and metadata."; + description = lib.mdDoc "Directory to store configuration and metadata."; }; settings = mkOption { @@ -159,14 +159,14 @@ in { example = literalExpression '' { videolibrary.showemptytvshows = "true"; } ''; - description = '' - Configuration to write to the advancedsettings.xml + description = lib.mdDoc '' + Configuration to write to the `advancedsettings.xml` file in kodis userdata directory. Settings specified here will be immutable from inside kodi and be hidden from the GUI settings dialog. - - See as + + See as reference for how settings need to be specified. - + The innermost attributes must be of type str. ''; }; @@ -190,17 +190,17 @@ in { }; } ''; - description = '' - Contents to populate the file sources.xml in kodis + description = lib.mdDoc '' + Contents to populate the file `sources.xml` in kodis userdata directory. - - See as + + See as reference for how sources need to be specified. - + Kodi will still show the dialogs to modify sources in the GUI and they appear to be mutable. This however is not the case and the sources will stay as specified via Home Manager. - + The innermost attributes must be of type str. ''; }; @@ -211,10 +211,10 @@ in { example = literalExpression '' { "service.xbmc.versioncheck".versioncheck_enable = "false"; } ''; - description = '' + description = lib.mdDoc '' Attribute set with the plugin namespace as toplevel key and the plugins settings as lower level key/value pairs. - + Kodi will still show the settings of plugins configured via this mechanism in the GUI and they appear to be mutable. This however is not the case and the settings will stay as specified via Home Manager. diff --git a/modules/programs/lazygit.nix b/modules/programs/lazygit.nix index 0c645cdc..979163b5 100644 --- a/modules/programs/lazygit.nix +++ b/modules/programs/lazygit.nix @@ -14,7 +14,8 @@ in { meta.maintainers = [ hm.maintainers.kalhauge ]; options.programs.lazygit = { - enable = mkEnableOption "lazygit, a simple terminal UI for git commands"; + enable = mkEnableOption + (lib.mdDoc "lazygit, a simple terminal UI for git commands"); package = mkPackageOptionMD pkgs "lazygit" { }; @@ -32,13 +33,13 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/lazygit/config.yml - on Linux or on Darwin if is set, otherwise - ~/Library/Application Support/lazygit/config.yml. + {file}`$XDG_CONFIG_HOME/lazygit/config.yml` + on Linux or on Darwin if [](#opt-xdg.enable) is set, otherwise + {file}`~/Library/Application Support/lazygit/config.yml`. See - + for supported values. ''; }; diff --git a/modules/programs/ledger.nix b/modules/programs/ledger.nix index d2538e1d..7fa3f2dd 100644 --- a/modules/programs/ledger.nix +++ b/modules/programs/ledger.nix @@ -19,7 +19,8 @@ in { meta.maintainers = [ ]; options.programs.ledger = { - enable = mkEnableOption "ledger, a double-entry accounting system"; + enable = + mkEnableOption (lib.mdDoc "ledger, a double-entry accounting system"); package = mkPackageOptionMD pkgs "ledger" { }; @@ -36,9 +37,9 @@ in { "~/finances/income.ledger" ]; }; - description = '' - Configuration written to $XDG_CONFIG_HOME/ledger/ledgerrc. - See + description = lib.mdDoc '' + Configuration written to {file}`$XDG_CONFIG_HOME/ledger/ledgerrc`. + See for explanation about possible values. ''; }; @@ -51,9 +52,9 @@ in { --effective --date-format %Y-%m-%d ''; - description = '' + description = lib.mdDoc '' Extra configuration to add to - $XDG_CONFIG_HOME/ledger/ledgerrc. + {file}`$XDG_CONFIG_HOME/ledger/ledgerrc`. ''; }; }; diff --git a/modules/programs/less.nix b/modules/programs/less.nix index 9e6e6720..f63409ad 100644 --- a/modules/programs/less.nix +++ b/modules/programs/less.nix @@ -8,7 +8,7 @@ in { options = { programs.less = { - enable = mkEnableOption "less, opposite of more"; + enable = mkEnableOption (lib.mdDoc "less, opposite of more"); keys = mkOption { type = types.lines; @@ -17,9 +17,9 @@ in { s back-line t forw-line ''; - description = '' - Extra configuration for less written to - $XDG_CONFIG_HOME/lesskey. + description = lib.mdDoc '' + Extra configuration for {command}`less` written to + {file}`$XDG_CONFIG_HOME/lesskey`. ''; }; }; diff --git a/modules/programs/lesspipe.nix b/modules/programs/lesspipe.nix index a7a51ffe..ce2cae42 100644 --- a/modules/programs/lesspipe.nix +++ b/modules/programs/lesspipe.nix @@ -7,7 +7,7 @@ with lib; options = { programs.lesspipe = { - enable = mkEnableOption "lesspipe preprocessor for less"; + enable = mkEnableOption (lib.mdDoc "lesspipe preprocessor for less"); }; }; diff --git a/modules/programs/lf.nix b/modules/programs/lf.nix index a30425c5..877d22f2 100644 --- a/modules/programs/lf.nix +++ b/modules/programs/lf.nix @@ -56,13 +56,13 @@ in { options = { programs.lf = { - enable = mkEnableOption "lf"; + enable = mkEnableOption (lib.mdDoc "lf"); package = mkOption { type = types.package; default = pkgs.lf; defaultText = literalExpression "pkgs.lf"; - description = '' + description = lib.mdDoc '' lf package to use. ''; }; @@ -99,7 +99,7 @@ in { get-mime-type = ''%xdg-mime query filetype "$f"''; open = "$$OPENER $f"; }; - description = '' + description = lib.mdDoc '' Commands to declare. Commands set to null or an empty string are deleted. ''; @@ -115,7 +115,7 @@ in { U = "!du -sh"; gg = null; }; - description = + description = lib.mdDoc "Keys to bind. Keys set to null or an empty string are deleted."; }; @@ -123,7 +123,7 @@ in { type = with types; attrsOf (nullOr str); default = { }; example = literalExpression ''{ "" = "cmd-escape"; }''; - description = '' + description = lib.mdDoc '' Keys to bind to command line commands which can only be one of the builtin commands. Keys set to null or an empty string are deleted. ''; @@ -146,9 +146,9 @@ in { esac ''' ''; - description = '' + description = lib.mdDoc '' Script or executable to use to preview files. Sets lf's - previewer option. + {var}`previewer` option. ''; }; @@ -156,8 +156,8 @@ in { type = with types; nullOr str; default = null; example = "i"; - description = '' - Key to bind to the script at previewer.source and + description = lib.mdDoc '' + Key to bind to the script at {var}`previewer.source` and pipe through less. Setting to null will not bind any key. ''; }; @@ -168,7 +168,7 @@ in { example = '' $mkdir -p ~/.trash ''; - description = "Custom lfrc lines."; + description = lib.mdDoc "Custom lfrc lines."; }; }; }; diff --git a/modules/programs/librewolf.nix b/modules/programs/librewolf.nix index 99613d46..24be5dd4 100644 --- a/modules/programs/librewolf.nix +++ b/modules/programs/librewolf.nix @@ -18,14 +18,14 @@ in { meta.maintainers = [ maintainers.onny ]; options.programs.librewolf = { - enable = - mkEnableOption "Librewolf browser, a privacy enhanced Firefox fork"; + enable = mkEnableOption + (lib.mdDoc "Librewolf browser, a privacy enhanced Firefox fork"); package = mkOption { type = types.package; default = pkgs.librewolf; defaultText = literalExpression "pkgs.librewolf"; - description = "The LibreWolf package to use."; + description = lib.mdDoc "The LibreWolf package to use."; }; settings = mkOption { @@ -37,9 +37,9 @@ in { "privacy.resistFingerprinting" = false; } ''; - description = '' + description = lib.mdDoc '' Attribute set of LibreWolf settings and overrides. Refer to - + for details on supported values. ''; }; diff --git a/modules/programs/lieer.nix b/modules/programs/lieer.nix index 15fda1ae..1916a262 100644 --- a/modules/programs/lieer.nix +++ b/modules/programs/lieer.nix @@ -35,7 +35,7 @@ let drop_non_existing_label = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Allow missing labels on the Gmail side to be dropped. ''; }; @@ -44,7 +44,7 @@ let type = types.str; default = ""; example = "mbox"; - description = '' + description = lib.mdDoc '' Extension to include in local file names, which can be useful for indexing with third-party programs. ''; @@ -53,12 +53,12 @@ let ignore_empty_history = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Work around a Gmail API quirk where an empty change history is sometimes returned. - + See this - GitHub issue + [GitHub issue](https://github.com/gauteh/lieer/issues/120) for more details. ''; }; @@ -72,7 +72,7 @@ let "CATEGORY_SOCIAL" "CATEGORY_PERSONAL" ]; - description = '' + description = lib.mdDoc '' Set Gmail labels to ignore when syncing from remote labels to local tags (before translations). ''; @@ -81,7 +81,7 @@ let ignore_tags = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' Set labels to ignore when syncing from local tags to remote labels (after translations). ''; @@ -90,7 +90,7 @@ let local_trash_tag = mkOption { type = types.str; default = "trash"; - description = '' + description = lib.mdDoc '' Local tag to which the remote Gmail 'TRASH' label is translated. ''; }; @@ -98,7 +98,7 @@ let remove_local_messages = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Remove local messages that have been deleted on the remote. ''; }; @@ -106,7 +106,7 @@ let replace_slash_with_dot = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Replace '/' with '.' in Gmail labels. ''; }; @@ -114,42 +114,40 @@ let timeout = mkOption { type = types.ints.unsigned; default = 600; - description = '' + description = lib.mdDoc '' HTTP timeout in seconds. 0 means forever or system timeout. ''; }; }; syncOpts = { - enable = mkEnableOption "lieer synchronization service"; + enable = mkEnableOption (lib.mdDoc "lieer synchronization service"); frequency = mkOption { type = types.str; default = "*:0/5"; - description = '' + description = lib.mdDoc '' How often to synchronize the account. - + This value is passed to the systemd timer configuration as the onCalendar option. See - - systemd.time - 7 - + {manpage}`systemd.time(7)` for more information about the format. ''; }; }; lieerOpts = { - enable = mkEnableOption "lieer Gmail synchronization for notmuch"; + enable = + mkEnableOption (lib.mdDoc "lieer Gmail synchronization for notmuch"); notmuchSetupWarning = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Warn if Notmuch is not also enabled for this account. - - This can safely be disabled if notmuch init + + This can safely be disabled if {command}`notmuch init` has been used to configure this account outside of Home Manager. ''; @@ -161,11 +159,11 @@ let options = settingsOpts; }; default = { }; - description = '' - Settings which are applied to .gmailieer.json + description = lib.mdDoc '' + Settings which are applied to {file}`.gmailieer.json` for the account. - - See the lieer manual + + See the [lieer manual](https://github.com/gauteh/lieer/) for documentation of settings not explicitly covered by this module. ''; }; @@ -234,13 +232,14 @@ in { options = { programs.lieer = { - enable = mkEnableOption "lieer Gmail synchronization for notmuch"; + enable = + mkEnableOption (lib.mdDoc "lieer Gmail synchronization for notmuch"); package = mkOption { type = types.package; default = pkgs.lieer; defaultText = "pkgs.lieer"; - description = '' + description = lib.mdDoc '' lieer package to use. ''; }; diff --git a/modules/programs/looking-glass-client.nix b/modules/programs/looking-glass-client.nix index 7628c27c..55036a56 100644 --- a/modules/programs/looking-glass-client.nix +++ b/modules/programs/looking-glass-client.nix @@ -9,14 +9,14 @@ in { meta.maintainers = with maintainers; [ j-brn ]; options.programs.looking-glass-client = { - enable = mkEnableOption "looking-glass-client"; + enable = mkEnableOption (lib.mdDoc "looking-glass-client"); package = mkPackageOptionMD pkgs "looking-glass-client" { }; settings = mkOption { type = settingsFormat.type; default = { }; - description = "looking-glass-client settings."; + description = lib.mdDoc "looking-glass-client settings."; example = literalExpression '' { app = { diff --git a/modules/programs/lsd.nix b/modules/programs/lsd.nix index a7f81c74..02390e49 100644 --- a/modules/programs/lsd.nix +++ b/modules/programs/lsd.nix @@ -21,12 +21,12 @@ in { meta.maintainers = [ ]; options.programs.lsd = { - enable = mkEnableOption "lsd"; + enable = mkEnableOption (lib.mdDoc "lsd"); enableAliases = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable recommended lsd aliases. ''; }; @@ -38,10 +38,10 @@ in { date = "relative"; ignore-globs = [ ".git" ".hg" ]; }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/lsd/config.yaml. See - + {file}`$XDG_CONFIG_HOME/lsd/config.yaml`. See + for supported values. ''; }; diff --git a/modules/programs/man.nix b/modules/programs/man.nix index f757fad5..d7bdf30e 100644 --- a/modules/programs/man.nix +++ b/modules/programs/man.nix @@ -9,10 +9,10 @@ in { enable = mkOption { type = types.bool; default = true; - description = '' - Whether to enable manual pages and the man + description = lib.mdDoc '' + Whether to enable manual pages and the {command}`man` command. This also includes "man" outputs of all - home.packages. + `home.packages`. ''; }; @@ -20,23 +20,17 @@ in { type = types.package; default = pkgs.man; defaultText = literalExpression "pkgs.man"; - description = "The man package to use."; + description = lib.mdDoc "The man package to use."; }; generateCaches = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to generate the manual page index caches using - - mandb - 8 - . This allows searching for a page or - keyword using utilities like - apropos - 1 - . - + {manpage}`mandb(8)`. This allows searching for a page or + keyword using utilities like {manpage}`apropos(1)`. + This feature is disabled by default because it slows down building. If you don't mind waiting a few more seconds when Home Manager builds a new generation, you may safely enable diff --git a/modules/programs/mangohud.nix b/modules/programs/mangohud.nix index f095e073..beb80c4d 100644 --- a/modules/programs/mangohud.nix +++ b/modules/programs/mangohud.nix @@ -26,19 +26,19 @@ let in { options = { programs.mangohud = { - enable = mkEnableOption "Mangohud"; + enable = mkEnableOption (lib.mdDoc "Mangohud"); package = mkOption { type = types.package; default = pkgs.mangohud; defaultText = literalExpression "pkgs.mangohud"; - description = "The Mangohud package to install."; + description = lib.mdDoc "The Mangohud package to install."; }; enableSessionWide = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Sets environment variables so that MangoHud is started on any application that supports it. ''; @@ -53,10 +53,10 @@ in { full = true; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/MangoHud/MangoHud.conf. See - + {file}`$XDG_CONFIG_HOME/MangoHud/MangoHud.conf`. See + for the default configuration. ''; }; @@ -71,11 +71,11 @@ in { } } ''; - description = '' + description = lib.mdDoc '' Sets MangoHud settings per application. Configuration written to - $XDG_CONFIG_HOME/MangoHud/{application_name}.conf. See - + {file}`$XDG_CONFIG_HOME/MangoHud/{application_name}.conf`. See + for the default configuration. ''; }; diff --git a/modules/programs/matplotlib.nix b/modules/programs/matplotlib.nix index 1edb9b12..99370328 100644 --- a/modules/programs/matplotlib.nix +++ b/modules/programs/matplotlib.nix @@ -19,13 +19,14 @@ in { meta.maintainers = [ maintainers.rprospero ]; options.programs.matplotlib = { - enable = mkEnableOption "matplotlib, a plotting library for python"; + enable = + mkEnableOption (lib.mdDoc "matplotlib, a plotting library for python"); config = mkOption { default = { }; type = types.attrsOf types.anything; - description = '' - Add terms to the matplotlibrc file to + description = lib.mdDoc '' + Add terms to the {file}`matplotlibrc` file to control the default matplotlib behavior. ''; example = literalExpression '' @@ -44,9 +45,9 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional commands for matplotlib that will be added to the - matplotlibrc file. + {file}`matplotlibrc` file. ''; }; }; diff --git a/modules/programs/mbsync-accounts.nix b/modules/programs/mbsync-accounts.nix index af368b9d..62b74515 100644 --- a/modules/programs/mbsync-accounts.nix +++ b/modules/programs/mbsync-accounts.nix @@ -14,7 +14,7 @@ let # Make value of name the same as the name used with the dot prefix default = name; readOnly = true; - description = '' + description = lib.mdDoc '' The name of this group for this account. These names are different than some others, because they will hide channel names that are the same. ''; @@ -23,11 +23,11 @@ let channels = mkOption { type = types.attrsOf (types.submodule channel); default = { }; - description = '' + description = lib.mdDoc '' List of channels that should be grouped together into this group. When performing a synchronization, the groups are synchronized, rather than the individual channels. - + Using these channels and then grouping them together allows for you to define the maildir hierarchy as you see fit. ''; @@ -42,10 +42,10 @@ let type = types.str; default = name; readOnly = true; - description = '' + description = lib.mdDoc '' The unique name for THIS channel in THIS group. The group will refer to this channel by this name. - + In addition, you can manually sync just this channel by specifying this name to mbsync on the command line. ''; @@ -55,14 +55,14 @@ let type = types.str; default = ""; example = "[Gmail]/Sent Mail"; - description = '' + description = lib.mdDoc '' IMAP4 patterns for which mailboxes on the remote mail server to sync. - If Patterns are specified, farPattern + If `Patterns` are specified, `farPattern` is interpreted as a prefix which is not matched against the patterns, and is not affected by mailbox list overrides. - + If this is left as the default, then mbsync will default to the pattern - INBOX. + `INBOX`. ''; }; @@ -70,13 +70,13 @@ let type = types.str; default = ""; example = "Sent"; - description = '' + description = lib.mdDoc '' Name for where mail coming from the remote (far) mail server will end up locally. The mailbox specified by the far pattern will be placed in this directory. - + If this is left as the default, then mbsync will default to the pattern - INBOX. + `INBOX`. ''; }; @@ -84,9 +84,9 @@ let type = types.listOf types.str; default = [ ]; example = [ "INBOX" ]; - description = '' - Instead of synchronizing just the mailboxes that - match the farPattern, use it as a prefix which is + description = lib.mdDoc '' + Instead of synchronizing *just* the mailboxes that + match the `farPattern`, use it as a prefix which is not matched against the patterns, and is not affected by mailbox list overrides. ''; @@ -103,8 +103,8 @@ let MaxSize = "1m"; } ''; - description = '' - Extra configuration lines to add to THIS channel's + description = lib.mdDoc '' + Extra configuration lines to add to *THIS* channel's configuration. ''; }; @@ -113,16 +113,16 @@ let in { options.mbsync = { - enable = mkEnableOption "synchronization using mbsync"; + enable = mkEnableOption (lib.mdDoc "synchronization using mbsync"); flatten = mkOption { type = types.nullOr types.str; default = null; example = "."; - description = '' + description = lib.mdDoc '' If set, flattens the hierarchy within the maildir by substituting the canonical hierarchy delimiter - / with this value. + `/` with this value. ''; }; @@ -130,9 +130,9 @@ in { type = types.enum [ "Verbatim" "Maildir++" "Legacy" ]; default = "Verbatim"; example = "Maildir++"; - description = '' + description = lib.mdDoc '' The on-disk folder naming style. This option has no - effect when is used. + effect when {option}`flatten` is used. ''; }; @@ -140,7 +140,7 @@ in { type = types.enum [ "none" "maildir" "imap" "both" ]; default = "none"; example = "maildir"; - description = '' + description = lib.mdDoc '' Automatically create missing mailboxes within the given mail store. ''; @@ -150,7 +150,7 @@ in { type = types.enum [ "none" "maildir" "imap" "both" ]; default = "none"; example = "imap"; - description = '' + description = lib.mdDoc '' Propagate mailbox deletions to the given mail store. ''; }; @@ -159,7 +159,7 @@ in { type = types.enum [ "none" "maildir" "imap" "both" ]; default = "none"; example = "both"; - description = '' + description = lib.mdDoc '' Permanently remove messages marked for deletion from the given mail store. ''; @@ -168,7 +168,7 @@ in { patterns = mkOption { type = types.listOf types.str; default = [ "*" ]; - description = '' + description = lib.mdDoc '' Pattern of mailboxes to synchronize. ''; }; @@ -179,12 +179,12 @@ in { # The default cannot actually be empty, but contains an attribute set where # the channels set is empty. If a group is specified, then a name is given, # creating the attribute set. - description = '' + description = lib.mdDoc '' Some email providers (Gmail) have a different directory hierarchy for synchronized email messages. Namely, when using mbsync without specifying a set of channels into a group, all synchronized directories end up beneath - the [Gmail]/ directory. - + the `[Gmail]/` directory. + This option allows you to specify a group, and subsequently channels that will allow you to sync your mail into an arbitrary hierarchy. ''; @@ -199,7 +199,7 @@ in { MaxSize = "1m"; }; ''; - description = '' + description = lib.mdDoc '' Per channel extra configuration. ''; }; @@ -207,7 +207,7 @@ in { extraConfig.local = mkOption { type = extraConfigType; default = { }; - description = '' + description = lib.mdDoc '' Local store extra configuration. ''; }; @@ -215,7 +215,7 @@ in { extraConfig.remote = mkOption { type = extraConfigType; default = { }; - description = '' + description = lib.mdDoc '' Remote store extra configuration. ''; }; @@ -229,7 +229,7 @@ in { Timeout = 60; }; ''; - description = '' + description = lib.mdDoc '' Account section extra configuration. ''; }; diff --git a/modules/programs/mbsync.nix b/modules/programs/mbsync.nix index d43f6455..4347c787 100644 --- a/modules/programs/mbsync.nix +++ b/modules/programs/mbsync.nix @@ -192,14 +192,15 @@ in { options = { programs.mbsync = { - enable = mkEnableOption "mbsync IMAP4 and Maildir mailbox synchronizer"; + enable = mkEnableOption + (lib.mdDoc "mbsync IMAP4 and Maildir mailbox synchronizer"); package = mkOption { type = types.package; default = pkgs.isync; defaultText = literalExpression "pkgs.isync"; example = literalExpression "pkgs.isync"; - description = "The package to use for the mbsync binary."; + description = lib.mdDoc "The package to use for the mbsync binary."; }; groups = mkOption { @@ -213,7 +214,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Definition of groups. ''; }; @@ -221,7 +222,7 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration lines to add to the mbsync configuration. ''; }; diff --git a/modules/programs/mcfly.nix b/modules/programs/mcfly.nix index 75f6f2b3..ed44ccbc 100644 --- a/modules/programs/mcfly.nix +++ b/modules/programs/mcfly.nix @@ -20,12 +20,12 @@ in { ]; options.programs.mcfly = { - enable = mkEnableOption "mcfly"; + enable = mkEnableOption (lib.mdDoc "mcfly"); keyScheme = mkOption { type = types.enum [ "emacs" "vim" ]; default = "emacs"; - description = '' + description = lib.mdDoc '' Key scheme to use. ''; }; @@ -33,7 +33,7 @@ in { enableLightTheme = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable light mode theme. ''; }; @@ -41,7 +41,7 @@ in { fuzzySearchFactor = mkOption { default = 0; type = types.ints.unsigned; - description = '' + description = lib.mdDoc '' Whether to enable fuzzy searching. 0 is off; higher numbers weight toward shorter matches. Values in the 2-5 range get good results so far. @@ -51,7 +51,7 @@ in { enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -59,7 +59,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -67,7 +67,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/mercurial.nix b/modules/programs/mercurial.nix index 07a7d626..95f5b3b7 100644 --- a/modules/programs/mercurial.nix +++ b/modules/programs/mercurial.nix @@ -12,35 +12,35 @@ in { options = { programs.mercurial = { - enable = mkEnableOption "Mercurial"; + enable = mkEnableOption (lib.mdDoc "Mercurial"); package = mkOption { type = types.package; default = pkgs.mercurial; defaultText = literalExpression "pkgs.mercurial"; - description = "Mercurial package to install."; + description = lib.mdDoc "Mercurial package to install."; }; userName = mkOption { type = types.str; - description = "Default user name to use."; + description = lib.mdDoc "Default user name to use."; }; userEmail = mkOption { type = types.str; - description = "Default user email to use."; + description = lib.mdDoc "Default user email to use."; }; aliases = mkOption { type = types.attrsOf types.anything; default = { }; - description = "Mercurial aliases to define."; + description = lib.mdDoc "Mercurial aliases to define."; }; extraConfig = mkOption { type = types.either (types.attrsOf types.anything) types.lines; default = { }; - description = "Additional configuration to add."; + description = lib.mdDoc "Additional configuration to add."; }; iniContent = mkOption { @@ -52,14 +52,15 @@ in { type = types.listOf types.str; default = [ ]; example = [ "*~" "*.swp" ]; - description = "List of globs for files to be globally ignored."; + description = + lib.mdDoc "List of globs for files to be globally ignored."; }; ignoresRegexp = mkOption { type = types.listOf types.str; default = [ ]; example = [ "^.*~$" "^.*\\.swp$" ]; - description = + description = lib.mdDoc "List of regular expressions for files to be globally ignored."; }; }; diff --git a/modules/programs/micro.nix b/modules/programs/micro.nix index f2f8b6bf..f748b413 100644 --- a/modules/programs/micro.nix +++ b/modules/programs/micro.nix @@ -13,7 +13,7 @@ in { options = { programs.micro = { - enable = mkEnableOption "micro, a terminal-based text editor"; + enable = mkEnableOption (lib.mdDoc "micro, a terminal-based text editor"); settings = mkOption { type = jsonFormat.type; @@ -24,10 +24,10 @@ in { cursorline = false; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/micro/settings.json. See - + {file}`$XDG_CONFIG_HOME/micro/settings.json`. See + for supported values. ''; }; diff --git a/modules/programs/mpv.nix b/modules/programs/mpv.nix index 1d0b24d4..3d0c58e1 100644 --- a/modules/programs/mpv.nix +++ b/modules/programs/mpv.nix @@ -61,14 +61,14 @@ let in { options = { programs.mpv = { - enable = mkEnableOption "mpv"; + enable = mkEnableOption (lib.mdDoc "mpv"); package = mkOption { type = types.package; default = pkgs.mpv; example = literalExpression "pkgs.wrapMpv (pkgs.mpv-unwrapped.override { vapoursynthSupport = true; }) { youtubeSupport = true; }"; - description = '' + description = lib.mdDoc '' Package providing mpv. ''; }; @@ -77,7 +77,7 @@ in { type = types.package; readOnly = true; visible = false; - description = '' + description = lib.mdDoc '' Resulting mpv package. ''; }; @@ -86,19 +86,16 @@ in { type = with types; listOf package; default = [ ]; example = literalExpression "[ pkgs.mpvScripts.mpris ]"; - description = '' + description = lib.mdDoc '' List of scripts to use with mpv. ''; }; scriptOpts = mkOption { - description = '' + description = lib.mdDoc '' Script options added to - $XDG_CONFIG_HOME/mpv/script-opts/. See - - mpv - 1 - + {file}`$XDG_CONFIG_HOME/mpv/script-opts/`. See + {manpage}`mpv(1)` for the full list of options of builtin scripts. ''; type = types.attrsOf mpvOptions; @@ -113,13 +110,10 @@ in { }; config = mkOption { - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/mpv/mpv.conf. See - - mpv - 1 - + {file}`$XDG_CONFIG_HOME/mpv/mpv.conf`. See + {manpage}`mpv(1)` for the full list of options. ''; type = mpvOptions; @@ -135,10 +129,10 @@ in { }; profiles = mkOption { - description = '' + description = lib.mdDoc '' Sub-configuration options for specific profiles written to - $XDG_CONFIG_HOME/mpv/mpv.conf. See - for more information. + {file}`$XDG_CONFIG_HOME/mpv/mpv.conf`. See + {option}`programs.mpv.config` for more information. ''; type = mpvProfiles; default = { }; @@ -156,9 +150,9 @@ in { }; defaultProfiles = mkOption { - description = '' + description = lib.mdDoc '' Profiles to be applied by default. Options set by them are overridden - by options set in . + by options set in [](#opt-programs.mpv.config). ''; type = mpvDefaultProfiles; default = [ ]; @@ -166,13 +160,10 @@ in { }; bindings = mkOption { - description = '' + description = lib.mdDoc '' Input configuration written to - $XDG_CONFIG_HOME/mpv/input.conf. See - - mpv - 1 - + {file}`$XDG_CONFIG_HOME/mpv/input.conf`. See + {manpage}`mpv(1)` for the full list of options. ''; type = mpvBindings; diff --git a/modules/programs/mr.nix b/modules/programs/mr.nix index ee1caf04..3975dc72 100644 --- a/modules/programs/mr.nix +++ b/modules/programs/mr.nix @@ -15,16 +15,16 @@ in { options.programs.mr = { enable = mkEnableOption - "mr, a tool to manage all your version control repositories"; + (lib.mdDoc "mr, a tool to manage all your version control repositories"); package = mkPackageOptionMD pkgs "mr" { }; settings = mkOption { type = iniFormat.type; default = { }; - description = '' - Configuration written to $HOME/.mrconfig - See + description = lib.mdDoc '' + Configuration written to {file}`$HOME/.mrconfig` + See for an example configuration. ''; example = literalExpression '' diff --git a/modules/programs/msmtp-accounts.nix b/modules/programs/msmtp-accounts.nix index fc527347..8d45c873 100644 --- a/modules/programs/msmtp-accounts.nix +++ b/modules/programs/msmtp-accounts.nix @@ -7,17 +7,17 @@ with lib; enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable msmtp. - + If enabled then it is possible to use the - --account command line + `--account` command line option to send a message for a given account using the - msmtp or msmtpq tool. - For example, msmtp --account=private would + {command}`msmtp` or {command}`msmtpq` tool. + For example, {command}`msmtp --account=private` would send using the account defined in - . If the - --account option is not + {option}`accounts.email.accounts.private`. If the + `--account` option is not given then the primary account will be used. ''; }; @@ -27,10 +27,10 @@ with lib; types.nullOr (types.strMatching "([[:alnum:]]{2}:)+[[:alnum:]]{2}"); default = null; example = "my:SH:a2:56:ha:sh"; - description = '' + description = lib.mdDoc '' Fingerprint of a trusted TLS certificate. The fingerprint can be obtained by executing - msmtp --serverinfo --tls --tls-certcheck=off. + {command}`msmtp --serverinfo --tls --tls-certcheck=off`. ''; }; @@ -38,9 +38,9 @@ with lib; type = types.attrsOf types.str; default = { }; example = { auth = "login"; }; - description = '' - Extra configuration options to add to ~/.msmtprc. - See for + description = lib.mdDoc '' + Extra configuration options to add to {file}`~/.msmtprc`. + See for examples. ''; }; diff --git a/modules/programs/msmtp.nix b/modules/programs/msmtp.nix index 04e7be8e..81c86747 100644 --- a/modules/programs/msmtp.nix +++ b/modules/programs/msmtp.nix @@ -49,28 +49,28 @@ in { options = { programs.msmtp = { - enable = mkEnableOption "msmtp"; + enable = mkEnableOption (lib.mdDoc "msmtp"); extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra configuration lines to add to ~/.msmtprc. - See for examples. - + description = lib.mdDoc '' + Extra configuration lines to add to {file}`~/.msmtprc`. + See for examples. + Note, if running msmtp fails with the error message "account default was already defined" then you probably have an account command here. Account commands should be placed in - . + [](#opt-accounts.email.accounts._name_.msmtp.extraConfig). ''; }; extraAccounts = mkOption { type = types.lines; default = ""; - description = '' - Extra configuration lines to add to the end of ~/.msmtprc. - See for examples. + description = lib.mdDoc '' + Extra configuration lines to add to the end of {file}`~/.msmtprc`. + See for examples. ''; }; }; diff --git a/modules/programs/mu.nix b/modules/programs/mu.nix index 835be361..960a528f 100644 --- a/modules/programs/mu.nix +++ b/modules/programs/mu.nix @@ -27,7 +27,7 @@ in { options = { programs.mu = { - enable = mkEnableOption "mu, a maildir indexer and searcher"; + enable = mkEnableOption (lib.mdDoc "mu, a maildir indexer and searcher"); # No options/config file present for mu, and program author will not be # adding one soon. See https://github.com/djcb/mu/issues/882 for more @@ -36,8 +36,9 @@ in { accounts.email.accounts = mkOption { type = with types; - attrsOf - (submodule { options.mu.enable = mkEnableOption "mu indexing"; }); + attrsOf (submodule { + options.mu.enable = mkEnableOption (lib.mdDoc "mu indexing"); + }); }; }; diff --git a/modules/programs/mujmap.nix b/modules/programs/mujmap.nix index a9467820..75551df2 100644 --- a/modules/programs/mujmap.nix +++ b/modules/programs/mujmap.nix @@ -50,7 +50,7 @@ let lowercase = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' If true, translate all mailboxes to lowercase names when mapping to notmuch tags. ''; @@ -60,7 +60,7 @@ let type = types.str; default = "/"; example = "."; - description = '' + description = lib.mdDoc '' Directory separator for mapping notmuch tags to maildirs. ''; }; @@ -68,71 +68,71 @@ let inbox = mkOption { type = types.str; default = "inbox"; - description = '' + description = lib.mdDoc '' Tag for notmuch to use for messages stored in the mailbox labeled with the - Inbox name attribute. - - If set to an empty string, this mailbox and its child - mailboxes are not synchronized with a tag. + `Inbox` name attribute. + + If set to an empty string, this mailbox *and its child + mailboxes* are not synchronized with a tag. ''; }; deleted = mkOption { type = types.str; default = "deleted"; - description = '' + description = lib.mdDoc '' Tag for notmuch to use for messages stored in the mailbox labeled with the - Trash name attribute. - - If set to an empty string, this mailbox and its child - mailboxes are not synchronized with a tag. + `Trash` name attribute. + + If set to an empty string, this mailbox *and its child + mailboxes* are not synchronized with a tag. ''; }; sent = mkOption { type = types.str; default = "sent"; - description = '' + description = lib.mdDoc '' Tag for notmuch to use for messages stored in the mailbox labeled with the - Sent name attribute. - - If set to an empty string, this mailbox and its child - mailboxes are not synchronized with a tag. + `Sent` name attribute. + + If set to an empty string, this mailbox *and its child + mailboxes* are not synchronized with a tag. ''; }; spam = mkOption { type = types.str; default = "spam"; - description = '' + description = lib.mdDoc '' Tag for notmuch to use for messages stored in the mailbox labeled with the - Junk name attribute and/or with the $Junk keyword, - except for messages with the $NotJunk keyword. - - If set to an empty string, this mailbox, its child - mailboxes, and these keywords are not synchronized with a tag. + `Junk` name attribute and/or with the `$Junk` keyword, + *except* for messages with the `$NotJunk` keyword. + + If set to an empty string, this mailbox, *its child + mailboxes*, and these keywords are not synchronized with a tag. ''; }; important = mkOption { type = types.str; default = "important"; - description = '' + description = lib.mdDoc '' Tag for notmuch to use for messages stored in the mailbox labeled with the - Important name attribute and/or with the $Important + `Important` name attribute and/or with the `$Important` keyword. - - If set to an empty string, this mailbox, its child - mailboxes, and these keywords are not synchronized with a tag. + + If set to an empty string, this mailbox, *its child + mailboxes*, and these keywords are not synchronized with a tag. ''; }; phishing = mkOption { type = types.str; default = "phishing"; - description = '' - Tag for notmuch to use for the IANA $Phishing keyword. - + description = lib.mdDoc '' + Tag for notmuch to use for the IANA `$Phishing` keyword. + If set to an empty string, this keyword is not synchronized with a tag. ''; }; @@ -143,11 +143,11 @@ let type = types.nullOr types.str; default = null; example = "alice@example.com"; - description = '' + description = lib.mdDoc '' Username for basic HTTP authentication. - - If null, defaults to - . + + If `null`, defaults to + [](#opt-accounts.email.accounts._name_.userName). ''; }; @@ -156,12 +156,12 @@ let default = null; apply = p: if isList p then escapeShellArgs p else p; example = "pass alice@example.com"; - description = '' + description = lib.mdDoc '' Shell command which will print a password to stdout for basic HTTP authentication. - - If null, defaults to - . + + If `null`, defaults to + [](#opt-accounts.email.accounts._name_.passwordCommand). ''; }; @@ -169,15 +169,15 @@ let type = types.nullOr types.str; default = null; example = "example.com"; - description = '' + description = lib.mdDoc '' Fully qualified domain name of the JMAP service. - + mujmap looks up the JMAP SRV record for this host to determine the JMAP session URL. Mutually exclusive with - . - - If null, defaults to - . + [](#opt-accounts.email.accounts._name_.mujmap.settings.session_url). + + If `null`, defaults to + [](#opt-accounts.email.accounts._name_.jmap.host). ''; }; @@ -185,21 +185,21 @@ let type = types.nullOr types.str; default = null; example = "https://jmap.example.com/.well-known/jmap"; - description = '' + description = lib.mdDoc '' Session URL to connect to. - + Mutually exclusive with - . - - If null, defaults to - . + [](#opt-accounts.email.accounts._name_.mujmap.settings.fqdn). + + If `null`, defaults to + [](#opt-accounts.email.accounts._name_.jmap.sessionUrl). ''; }; auto_create_new_mailboxes = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to create new mailboxes automatically on the server from notmuch tags. ''; @@ -208,7 +208,7 @@ let cache_dir = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The cache directory in which to store mail files while they are being downloaded. The default is operating-system specific. ''; @@ -220,27 +220,28 @@ let options = tagsOpts; }; default = { }; - description = '' + description = lib.mdDoc '' Tag configuration. - + Beware that there are quirks that require manual consideration if changing the values of these files; please see - + for more details. ''; }; }; mujmapOpts = { - enable = mkEnableOption "mujmap JMAP synchronization for notmuch"; + enable = + mkEnableOption (lib.mdDoc "mujmap JMAP synchronization for notmuch"); notmuchSetupWarning = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Warn if Notmuch is not also enabled for this account. - - This can safely be disabled if mujmap.toml is managed + + This can safely be disabled if {file}`mujmap.toml` is managed outside of Home Manager. ''; }; @@ -251,11 +252,11 @@ let options = rootOpts; }; default = { }; - description = '' - Settings which are applied to mujmap.toml + description = lib.mdDoc '' + Settings which are applied to {file}`mujmap.toml` for the account. - - See the mujmap project + + See the [mujmap project](https://github.com/elizagamedev/mujmap) for documentation of settings not explicitly covered by this module. ''; }; @@ -267,13 +268,14 @@ in { options = { programs.mujmap = { - enable = mkEnableOption "mujmap Gmail synchronization for notmuch"; + enable = + mkEnableOption (lib.mdDoc "mujmap Gmail synchronization for notmuch"); package = mkOption { type = types.package; default = pkgs.mujmap; defaultText = "pkgs.mujmap"; - description = '' + description = lib.mdDoc '' mujmap package to use. ''; }; diff --git a/modules/programs/navi.nix b/modules/programs/navi.nix index e33a4f38..adcd4cce 100644 --- a/modules/programs/navi.nix +++ b/modules/programs/navi.nix @@ -16,13 +16,13 @@ in { meta.maintainers = [ ]; options.programs.navi = { - enable = mkEnableOption "Navi"; + enable = mkEnableOption (lib.mdDoc "Navi"); package = mkOption { type = types.package; default = pkgs.navi; defaultText = literalExpression "pkgs.navi"; - description = "The package to use for the navi binary."; + description = lib.mdDoc "The package to use for the navi binary."; }; settings = mkOption { @@ -37,25 +37,25 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/navi/config.yaml on Linux or - $HOME/Library/Application Support/navi/config.yaml + {file}`$XDG_CONFIG_HOME/navi/config.yaml` on Linux or + {file}`$HOME/Library/Application Support/navi/config.yaml` on Darwin. See - + for more information. ''; }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = true; }; - enableFishIntegration = mkEnableOption "Fish integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish integration") // { default = true; }; }; diff --git a/modules/programs/ncmpcpp.nix b/modules/programs/ncmpcpp.nix index 11782855..8e4018b2 100644 --- a/modules/programs/ncmpcpp.nix +++ b/modules/programs/ncmpcpp.nix @@ -31,13 +31,14 @@ let options = { key = mkOption { type = types.str; - description = "Key to bind."; + description = lib.mdDoc "Key to bind."; example = "j"; }; command = mkOption { type = with types; either str (listOf str); - description = "Command or sequence of commands to be executed."; + description = + lib.mdDoc "Command or sequence of commands to be executed."; example = "scroll_down"; }; }; @@ -47,15 +48,15 @@ in { meta.maintainers = [ hm.maintainers.olmokramer ]; options.programs.ncmpcpp = { - enable = - mkEnableOption "ncmpcpp - an ncurses Music Player Daemon (MPD) client"; + enable = mkEnableOption + (lib.mdDoc "ncmpcpp - an ncurses Music Player Daemon (MPD) client"); package = mkOption { type = types.package; default = pkgs.ncmpcpp; defaultText = literalExpression "pkgs.ncmpcpp"; - description = '' - Package providing the ncmpcpp command. + description = lib.mdDoc '' + Package providing the `ncmpcpp` command. ''; example = literalExpression "pkgs.ncmpcpp.override { visualizerSupport = true; }"; @@ -74,11 +75,11 @@ in { else null ''; - description = '' - Value of the mpd_music_dir setting. On Linux platforms the - value of services.mpd.musicDirectory is used as the - default if services.mpd.enable is - true. + description = lib.mdDoc '' + Value of the `mpd_music_dir` setting. On Linux platforms the + value of {var}`services.mpd.musicDirectory` is used as the + default if {var}`services.mpd.enable` is + `true`. ''; example = "~/music"; }; @@ -86,13 +87,10 @@ in { settings = mkOption { type = types.attrsOf valueType; default = { }; - description = '' + description = lib.mdDoc '' Attribute set from name of a setting to its value. For available options see - - ncmpcpp - 1 - . + {manpage}`ncmpcpp(1)`. ''; example = { ncmpcpp_directory = "~/.local/share/ncmpcpp"; }; }; @@ -100,7 +98,7 @@ in { bindings = mkOption { type = types.listOf bindingType; default = [ ]; - description = "List of keybindings."; + description = lib.mdDoc "List of keybindings."; example = literalExpression '' [ { key = "j"; command = "scroll_down"; } diff --git a/modules/programs/ncspot.nix b/modules/programs/ncspot.nix index 97d809bd..841262b1 100644 --- a/modules/programs/ncspot.nix +++ b/modules/programs/ncspot.nix @@ -12,13 +12,13 @@ in { meta.maintainers = [ ]; options.programs.ncspot = { - enable = mkEnableOption "ncspot"; + enable = mkEnableOption (lib.mdDoc "ncspot"); package = mkOption { type = types.package; default = pkgs.ncspot; defaultText = literalExpression "pkgs.ncspot"; - description = "The package to use for ncspot."; + description = lib.mdDoc "The package to use for ncspot."; }; settings = mkOption { @@ -30,11 +30,11 @@ in { gapless = true; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/ncspot/config.toml. - - See + {file}`$XDG_CONFIG_HOME/ncspot/config.toml`. + + See for the full list of options. ''; }; diff --git a/modules/programs/ne.nix b/modules/programs/ne.nix index 1596066b..833070d4 100644 --- a/modules/programs/ne.nix +++ b/modules/programs/ne.nix @@ -22,7 +22,7 @@ in { meta.maintainers = [ hm.maintainers.cwyc ]; options.programs.ne = { - enable = mkEnableOption "ne"; + enable = mkEnableOption (lib.mdDoc "ne"); keybindings = mkOption { type = types.lines; @@ -31,7 +31,7 @@ in { KEY 7f BS SEQ "\x1b[1;5D" 7f ''; - description = '' + description = lib.mdDoc '' Keybinding file for ne. ''; }; @@ -39,10 +39,10 @@ in { defaultPreferences = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Default preferences for ne. - - Equivalent to programs.ne.automaticPreferences.".default". + + Equivalent to `programs.ne.automaticPreferences.".default"`. ''; }; @@ -60,7 +60,7 @@ in { '''; } ''; - description = '' + description = lib.mdDoc '' Automatic preferences files for ne. ''; }; @@ -68,7 +68,7 @@ in { menus = mkOption { type = types.lines; default = ""; - description = "Menu configuration file for ne."; + description = lib.mdDoc "Menu configuration file for ne."; }; virtualExtensions = mkOption { @@ -78,7 +78,7 @@ in { sh 1 ^#!\s*/.*\b(bash|sh|ksh|zsh)\s* csh 1 ^#!\s*/.*\b(csh|tcsh)\s* ''; - description = "Virtual extensions configuration file for ne."; + description = lib.mdDoc "Virtual extensions configuration file for ne."; }; }; diff --git a/modules/programs/neomutt-accounts.nix b/modules/programs/neomutt-accounts.nix index 27e3b122..ccf730f0 100644 --- a/modules/programs/neomutt-accounts.nix +++ b/modules/programs/neomutt-accounts.nix @@ -8,21 +8,23 @@ let mailbox = mkOption { type = types.str; example = "Sent"; - description = "Name of mailbox folder to be included"; + description = lib.mdDoc "Name of mailbox folder to be included"; }; name = mkOption { type = types.nullOr types.str; example = "Junk"; default = null; - description = "Name to display"; + description = lib.mdDoc "Name to display"; }; }; }; in { options.notmuch.neomutt = { - enable = mkEnableOption "Notmuch support in NeoMutt" // { default = true; }; + enable = mkEnableOption (lib.mdDoc "Notmuch support in NeoMutt") // { + default = true; + }; virtualMailboxes = mkOption { type = types.listOf (types.submodule ./notmuch-virtual-mailbox.nix); @@ -34,12 +36,12 @@ in { name = "My INBOX"; query = "tag:inbox"; }]; - description = "List of virtual mailboxes using Notmuch queries"; + description = lib.mdDoc "List of virtual mailboxes using Notmuch queries"; }; }; options.neomutt = { - enable = mkEnableOption "NeoMutt"; + enable = mkEnableOption (lib.mdDoc "NeoMutt"); sendMailCommand = mkOption { type = types.nullOr types.str; @@ -54,7 +56,7 @@ in { null ''; example = "msmtpq --read-envelope-from --read-recipients"; - description = '' + description = lib.mdDoc '' Command to send a mail. If not set, neomutt will be in charge of sending mails. ''; }; @@ -63,7 +65,7 @@ in { type = types.lines; default = ""; example = "color status cyan default"; - description = '' + description = lib.mdDoc '' Extra lines to add to the folder hook for this account. ''; }; @@ -72,13 +74,13 @@ in { type = types.nullOr types.str; default = null; example = "==== ==="; - description = "Use a different name as mailbox name"; + description = lib.mdDoc "Use a different name as mailbox name"; }; extraMailboxes = mkOption { type = with types; listOf (either str (submodule extraMailboxOptions)); default = [ ]; - description = "List of extra mailboxes"; + description = lib.mdDoc "List of extra mailboxes"; }; }; } diff --git a/modules/programs/neomutt.nix b/modules/programs/neomutt.nix index 65f3144f..e749148c 100644 --- a/modules/programs/neomutt.nix +++ b/modules/programs/neomutt.nix @@ -10,18 +10,18 @@ let sidebarModule = types.submodule { options = { - enable = mkEnableOption "sidebar support"; + enable = mkEnableOption (lib.mdDoc "sidebar support"); width = mkOption { type = types.int; default = 22; - description = "Width of the sidebar"; + description = lib.mdDoc "Width of the sidebar"; }; shortPath = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' By default sidebar shows the full path of the mailbox, but with this enabled only the relative name is shown. ''; @@ -30,7 +30,7 @@ let format = mkOption { type = types.str; default = "%D%?F? [%F]?%* %?N?%N/?%S"; - description = '' + description = lib.mdDoc '' Sidebar format. Check neomutt documentation for details. ''; }; @@ -71,19 +71,19 @@ let ]; in with types; either (enum menus) (listOf (enum menus)); default = "index"; - description = "Select the menu to bind the command to."; + description = lib.mdDoc "Select the menu to bind the command to."; }; key = mkOption { type = types.str; example = ""; - description = "The key to bind."; + description = lib.mdDoc "The key to bind."; }; action = mkOption { type = types.str; example = "toggle sidebar_visible"; - description = "Specify the action to take."; + description = lib.mdDoc "Specify the action to take."; }; }; }; @@ -251,31 +251,31 @@ let in { options = { programs.neomutt = { - enable = mkEnableOption "the NeoMutt mail client"; + enable = mkEnableOption (lib.mdDoc "the NeoMutt mail client"); package = mkOption { type = types.package; default = pkgs.neomutt; defaultText = literalExpression "pkgs.neomutt"; - description = "The neomutt package to use."; + description = lib.mdDoc "The neomutt package to use."; }; sidebar = mkOption { type = sidebarModule; default = { }; - description = "Options related to the sidebar."; + description = lib.mdDoc "Options related to the sidebar."; }; binds = mkOption { type = types.listOf bindModule; default = [ ]; - description = "List of keybindings."; + description = lib.mdDoc "List of keybindings."; }; macros = mkOption { type = types.listOf bindModule; default = [ ]; - description = "List of macros."; + description = lib.mdDoc "List of macros."; }; sort = mkOption { @@ -283,43 +283,44 @@ in { type = types.enum (sortOptions ++ (map (option: "reverse-" + option) sortOptions)); default = "threads"; - description = "Sorting method on messages."; + description = lib.mdDoc "Sorting method on messages."; }; vimKeys = mkOption { type = types.bool; default = false; - description = "Enable vim-like bindings."; + description = lib.mdDoc "Enable vim-like bindings."; }; checkStatsInterval = mkOption { type = types.nullOr types.int; default = null; example = 60; - description = "Enable and set the interval of automatic mail check."; + description = + lib.mdDoc "Enable and set the interval of automatic mail check."; }; editor = mkOption { type = types.str; default = "$EDITOR"; - description = "Select the editor used for writing mail."; + description = lib.mdDoc "Select the editor used for writing mail."; }; settings = mkOption { type = types.attrsOf types.str; default = { }; - description = "Extra configuration appended to the end."; + description = lib.mdDoc "Extra configuration appended to the end."; }; - changeFolderWhenSourcingAccount = - mkEnableOption "changing the folder when sourcing an account" // { + changeFolderWhenSourcingAccount = mkEnableOption + (lib.mdDoc "changing the folder when sourcing an account") // { default = true; }; extraConfig = mkOption { type = types.lines; default = ""; - description = "Extra configuration appended to the end."; + description = lib.mdDoc "Extra configuration appended to the end."; }; }; diff --git a/modules/programs/neovim.nix b/modules/programs/neovim.nix index a0519140..d28ad9cb 100644 --- a/modules/programs/neovim.nix +++ b/modules/programs/neovim.nix @@ -17,7 +17,7 @@ let options = { config = mkOption { type = types.nullOr types.lines; - description = + description = lib.mdDoc "Script to configure this plugin. The scripting language should match type."; default = null; }; @@ -25,18 +25,18 @@ let type = mkOption { type = types.either (types.enum [ "lua" "viml" "teal" "fennel" ]) types.str; - description = + description = lib.mdDoc "Language used in config. Configurations are aggregated per-language."; default = "viml"; }; - optional = mkEnableOption "optional" // { + optional = mkEnableOption (lib.mdDoc "optional") // { description = "Don't load by default (load with :packadd)"; }; plugin = mkOption { type = types.package; - description = "vim plugin"; + description = lib.mdDoc "vim plugin"; }; runtime = mkOption { @@ -97,37 +97,37 @@ in { options = { programs.neovim = { - enable = mkEnableOption "Neovim"; + enable = mkEnableOption (lib.mdDoc "Neovim"); viAlias = mkOption { type = types.bool; default = false; - description = '' - Symlink vi to nvim binary. + description = lib.mdDoc '' + Symlink {command}`vi` to {command}`nvim` binary. ''; }; vimAlias = mkOption { type = types.bool; default = false; - description = '' - Symlink vim to nvim binary. + description = lib.mdDoc '' + Symlink {command}`vim` to {command}`nvim` binary. ''; }; vimdiffAlias = mkOption { type = types.bool; default = false; - description = '' - Alias vimdiff to nvim -d. + description = lib.mdDoc '' + Alias {command}`vimdiff` to {command}`nvim -d`. ''; }; withNodeJs = mkOption { type = types.bool; default = false; - description = '' - Enable node provider. Set to true to + description = lib.mdDoc '' + Enable node provider. Set to `true` to use Node plugins. ''; }; @@ -135,7 +135,7 @@ in { withRuby = mkOption { type = types.nullOr types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable ruby provider. ''; }; @@ -143,8 +143,8 @@ in { withPython3 = mkOption { type = types.bool; default = true; - description = '' - Enable Python 3 provider. Set to true to + description = lib.mdDoc '' + Enable Python 3 provider. Set to `true` to use Python 3 plugins. ''; }; @@ -166,7 +166,7 @@ in { defaultText = literalExpression "ps: [ ]"; example = literalExpression "pyPkgs: with pyPkgs; [ python-language-server ]"; - description = '' + description = lib.mdDoc '' The extra Python 3 packages required for your plugins to work. This option accepts a function that takes a Python 3 package set as an argument, and selects the required Python 3 packages from this package set. @@ -190,7 +190,7 @@ in { default = _: [ ]; defaultText = literalExpression "ps: [ ]"; example = literalExpression "luaPkgs: with luaPkgs; [ luautf8 ]"; - description = '' + description = lib.mdDoc '' The extra Lua packages required for your plugins to work. This option accepts a function that takes a Lua package set as an argument, and selects the required Lua packages from this package set. @@ -202,7 +202,7 @@ in { type = types.lines; visible = true; readOnly = true; - description = '' + description = lib.mdDoc '' Generated vimscript config. ''; }; @@ -223,7 +223,7 @@ in { vim.opt.background = "dark" '''; }''; - description = '' + description = lib.mdDoc '' Generated configurations with as key their language (set via type). ''; }; @@ -232,22 +232,22 @@ in { type = types.package; default = pkgs.neovim-unwrapped; defaultText = literalExpression "pkgs.neovim-unwrapped"; - description = "The package to use for the neovim binary."; + description = lib.mdDoc "The package to use for the neovim binary."; }; finalPackage = mkOption { type = types.package; visible = false; readOnly = true; - description = "Resulting customized neovim package."; + description = lib.mdDoc "Resulting customized neovim package."; }; defaultEditor = mkOption { type = types.bool; default = false; - description = '' - Whether to configure nvim as the default - editor using the EDITOR environment variable. + description = lib.mdDoc '' + Whether to configure {command}`nvim` as the default + editor using the {env}`EDITOR` environment variable. ''; }; @@ -257,7 +257,7 @@ in { example = '' set nobackup ''; - description = '' + description = lib.mdDoc '' Custom vimrc lines. ''; }; @@ -268,7 +268,7 @@ in { example = '' vim.opt.nobackup = true ''; - description = '' + description = lib.mdDoc '' Custom lua lines. ''; }; @@ -277,7 +277,7 @@ in { type = with types; listOf package; default = [ ]; example = literalExpression "[ pkgs.shfmt ]"; - description = "Extra packages available to nvim."; + description = lib.mdDoc "Extra packages available to nvim."; }; plugins = mkOption { @@ -292,24 +292,22 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' List of vim plugins to install optionally associated with configuration to be placed in init.vim. - - - This option is mutually exclusive with configure. + This option is mutually exclusive with {var}`configure`. ''; }; coc = { - enable = mkEnableOption "Coc"; + enable = mkEnableOption (lib.mdDoc "Coc"); package = mkOption { type = types.package; default = pkgs.vimPlugins.coc-nvim; defaultText = literalExpression "pkgs.vimPlugins.coc-nvim"; - description = "The package to use for the CoC plugin."; + description = lib.mdDoc "The package to use for the CoC plugin."; }; settings = mkOption { @@ -337,11 +335,11 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' Extra configuration lines to add to - $XDG_CONFIG_HOME/nvim/coc-settings.json + {file}`$XDG_CONFIG_HOME/nvim/coc-settings.json` See - + for options. ''; }; @@ -349,7 +347,7 @@ in { pluginConfig = mkOption { type = types.lines; default = ""; - description = "Script to configure CoC. Must be viml."; + description = lib.mdDoc "Script to configure CoC. Must be viml."; }; }; }; diff --git a/modules/programs/newsboat.nix b/modules/programs/newsboat.nix index d2782bf2..d048bda7 100644 --- a/modules/programs/newsboat.nix +++ b/modules/programs/newsboat.nix @@ -37,7 +37,7 @@ in { options = { programs.newsboat = { - enable = mkEnableOption "the Newsboat feed reader"; + enable = mkEnableOption (lib.mdDoc "the Newsboat feed reader"); urls = mkOption { type = types.listOf (types.submodule { @@ -45,21 +45,21 @@ in { url = mkOption { type = types.str; example = "http://example.com"; - description = "Feed URL."; + description = lib.mdDoc "Feed URL."; }; tags = mkOption { type = types.listOf types.str; default = [ ]; example = [ "foo" "bar" ]; - description = "Feed tags."; + description = lib.mdDoc "Feed tags."; }; title = mkOption { type = types.nullOr types.str; default = null; example = "ORF News"; - description = "Feed title."; + description = lib.mdDoc "Feed title."; }; }; }); @@ -68,7 +68,7 @@ in { url = "http://example.com"; tags = [ "foo" "bar" ]; }]; - description = '' + description = lib.mdDoc '' List of news feeds. Leave it empty if you want to manage feeds imperatively, for example, using Syncthing. ''; @@ -77,19 +77,21 @@ in { maxItems = mkOption { type = types.int; default = 0; - description = "Maximum number of items per feed, 0 for infinite."; + description = + lib.mdDoc "Maximum number of items per feed, 0 for infinite."; }; reloadThreads = mkOption { type = types.int; default = 5; - description = "How many threads to use for updating the feeds."; + description = + lib.mdDoc "How many threads to use for updating the feeds."; }; autoReload = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable automatic reloading while newsboat is running. ''; }; @@ -97,26 +99,26 @@ in { reloadTime = mkOption { type = types.nullOr types.int; default = 60; - description = "Time in minutes between reloads."; + description = lib.mdDoc "Time in minutes between reloads."; }; browser = mkOption { type = types.str; default = "${pkgs.xdg-utils}/bin/xdg-open"; - description = "External browser to use."; + description = lib.mdDoc "External browser to use."; }; queries = mkOption { type = types.attrsOf types.str; default = { }; example = { "foo" = ''rssurl =~ "example.com"''; }; - description = "A list of queries to use."; + description = lib.mdDoc "A list of queries to use."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration values that will be appended to the end. ''; }; diff --git a/modules/programs/nheko.nix b/modules/programs/nheko.nix index 55b2616d..b159828e 100644 --- a/modules/programs/nheko.nix +++ b/modules/programs/nheko.nix @@ -22,7 +22,7 @@ in { meta.maintainers = [ maintainers.gvolpe ]; options.programs.nheko = { - enable = mkEnableOption "Qt desktop client for Matrix"; + enable = mkEnableOption (lib.mdDoc "Qt desktop client for Matrix"); package = mkPackageOptionMD pkgs "nheko" { }; @@ -47,19 +47,15 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Attribute set of Nheko preferences (converted to an INI file). - - For now, it is recommended to run nheko and sign-in before filling in the configuration settings in this module, as nheko writes the access - token to $XDG_CONFIG_HOME/nheko/nheko.conf the + token to {file}`$XDG_CONFIG_HOME/nheko/nheko.conf` the first time we sign in, and we need that data into these settings for the correct functionality of the application. - - This a temporary inconvenience, however, as nheko has plans to move the authentication stuff into the local database they currently use. Once this happens, this will no longer be an issue. diff --git a/modules/programs/nix-index.nix b/modules/programs/nix-index.nix index 2593d8b7..d8d604b2 100644 --- a/modules/programs/nix-index.nix +++ b/modules/programs/nix-index.nix @@ -4,24 +4,26 @@ in { meta.maintainers = with lib.hm.maintainers; [ ambroisie ]; options.programs.nix-index = with lib; { - enable = mkEnableOption "nix-index, a file database for nixpkgs"; + enable = + mkEnableOption (lib.mdDoc "nix-index, a file database for nixpkgs"); package = mkOption { type = types.package; default = pkgs.nix-index; defaultText = literalExpression "pkgs.nix-index"; - description = "Package providing the nix-index tool."; + description = + lib.mdDoc "Package providing the {command}`nix-index` tool."; }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = true; }; - enableFishIntegration = mkEnableOption "Fish integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish integration") // { default = true; }; }; diff --git a/modules/programs/nnn.nix b/modules/programs/nnn.nix index a32ac723..716cef4f 100644 --- a/modules/programs/nnn.nix +++ b/modules/programs/nnn.nix @@ -23,14 +23,14 @@ let }) + "/plugins"; ''; default = null; - description = '' + description = lib.mdDoc '' Path to the plugin folder. ''; }; mappings = mkOption { type = with types; attrsOf str; - description = '' + description = lib.mdDoc '' Key mappings to the plugins. ''; default = { }; @@ -49,7 +49,7 @@ in { options = { programs.nnn = { - enable = mkEnableOption "nnn"; + enable = mkEnableOption (lib.mdDoc "nnn"); package = mkOption { type = types.package; @@ -57,8 +57,8 @@ in { defaultText = literalExpression "pkgs.nnn"; example = literalExpression "pkgs.nnn.override ({ withNerdIcons = true; });"; - description = '' - Package containing the nnn program. + description = lib.mdDoc '' + Package containing the {command}`nnn` program. ''; }; @@ -66,14 +66,14 @@ in { type = types.package; readOnly = true; visible = false; - description = '' + description = lib.mdDoc '' Resulting nnn package. ''; }; bookmarks = mkOption { type = with types; attrsOf str; - description = '' + description = lib.mdDoc '' Directory bookmarks. ''; example = literalExpression '' @@ -91,7 +91,7 @@ in { type = with types; listOf package; example = literalExpression "with pkgs; [ ffmpegthumbnailer mediainfo sxiv ]"; - description = '' + description = lib.mdDoc '' Extra packages available to nnn. ''; default = [ ]; @@ -99,7 +99,7 @@ in { plugins = mkOption { type = pluginModule; - description = '' + description = lib.mdDoc '' Manage nnn plugins. ''; default = { }; diff --git a/modules/programs/noti.nix b/modules/programs/noti.nix index e7dc982e..1c354205 100644 --- a/modules/programs/noti.nix +++ b/modules/programs/noti.nix @@ -10,20 +10,17 @@ in { meta.maintainers = [ ]; options.programs.noti = { - enable = mkEnableOption "Noti"; + enable = mkEnableOption (lib.mdDoc "Noti"); settings = mkOption { type = types.attrsOf (types.attrsOf types.str); default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/noti/noti.yaml. - + {file}`$XDG_CONFIG_HOME/noti/noti.yaml`. + See - - noti.yaml - 5 - . + {manpage}`noti.yaml(5)`. for the full list of options. ''; example = literalExpression '' diff --git a/modules/programs/notmuch-virtual-mailbox.nix b/modules/programs/notmuch-virtual-mailbox.nix index 72a78842..3fc9163e 100644 --- a/modules/programs/notmuch-virtual-mailbox.nix +++ b/modules/programs/notmuch-virtual-mailbox.nix @@ -5,28 +5,29 @@ with lib; { type = types.str; example = "My INBOX"; default = "My INBOX"; - description = "Name to display"; + description = lib.mdDoc "Name to display"; }; query = mkOption { type = types.str; example = "tag:inbox"; default = "tag:inbox"; - description = "Notmuch query"; + description = lib.mdDoc "Notmuch query"; }; limit = mkOption { type = types.nullOr types.int; example = 10; default = null; - description = "Restricts number of messages/threads in the result."; + description = + lib.mdDoc "Restricts number of messages/threads in the result."; }; type = mkOption { type = types.nullOr (types.enum ([ "threads" "messages" ])); example = "threads"; default = null; - description = + description = lib.mdDoc "Reads all matching messages or whole-threads. The default is 'messages' or nm_query_type."; }; }; diff --git a/modules/programs/notmuch.nix b/modules/programs/notmuch.nix index 9c1c9f5c..886a4738 100644 --- a/modules/programs/notmuch.nix +++ b/modules/programs/notmuch.nix @@ -47,7 +47,7 @@ let in { options = { programs.notmuch = { - enable = mkEnableOption "Notmuch mail indexer"; + enable = mkEnableOption (lib.mdDoc "Notmuch mail indexer"); new = mkOption { type = types.submodule { @@ -55,9 +55,9 @@ in { ignore = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' A list to specify files and directories that will not be - searched for messages by notmuch new. + searched for messages by {command}`notmuch new`. ''; }; @@ -65,24 +65,24 @@ in { type = types.listOf types.str; default = [ "unread" "inbox" ]; example = [ "new" ]; - description = '' + description = lib.mdDoc '' A list of tags that will be added to all messages - incorporated by notmuch new. + incorporated by {command}`notmuch new`. ''; }; }; }; default = { }; - description = '' + description = lib.mdDoc '' Options related to email processing performed by - notmuch new. + {command}`notmuch new`. ''; }; extraConfig = mkOption { type = types.attrsOf (types.attrsOf types.str); default = { }; - description = '' + description = lib.mdDoc '' Options that should be appended to the notmuch configuration file. ''; }; @@ -92,7 +92,7 @@ in { type = types.lines; default = ""; example = "mbsync --all"; - description = '' + description = lib.mdDoc '' Bash statements run before scanning or importing new messages into the database. ''; @@ -104,7 +104,7 @@ in { example = '' notmuch tag +nixos -- tag:new and from:nixos1@discoursemail.com ''; - description = '' + description = lib.mdDoc '' Bash statements run after new messages have been imported into the database and initial tags have been applied. ''; @@ -113,7 +113,7 @@ in { postInsert = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Bash statements run after a message has been inserted into the database and initial tags have been applied. ''; @@ -124,7 +124,7 @@ in { synchronizeFlags = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to synchronize Maildir flags. ''; }; @@ -135,7 +135,7 @@ in { type = types.listOf types.str; default = [ "deleted" "spam" ]; example = [ "trash" "spam" ]; - description = '' + description = lib.mdDoc '' A list of tags that will be excluded from search results by default. Using an excluded tag in a query will override that exclusion. @@ -147,7 +147,8 @@ in { accounts.email.accounts = mkOption { type = with types; attrsOf (submodule { - options.notmuch.enable = mkEnableOption "notmuch indexing"; + options.notmuch.enable = + mkEnableOption (lib.mdDoc "notmuch indexing"); }); }; }; diff --git a/modules/programs/nushell.nix b/modules/programs/nushell.nix index b72cbb69..3ccd754a 100644 --- a/modules/programs/nushell.nix +++ b/modules/programs/nushell.nix @@ -22,8 +22,8 @@ let ""; defaultText = literalExpression "if source is defined, the content of source, otherwise empty"; - description = '' - Text of the nushell ${name} file. + description = lib.mdDoc '' + Text of the nushell {file}`${name}` file. If unset then the source option will be preferred. ''; }; @@ -31,8 +31,8 @@ let source = mkOption { type = types.nullOr types.path; default = null; - description = '' - Path of the nushell ${name} file to use. + description = lib.mdDoc '' + Path of the nushell {file}`${name}` file to use. If the text option is set, it will be preferred. ''; }; @@ -52,13 +52,13 @@ in { ]; options.programs.nushell = { - enable = mkEnableOption "nushell"; + enable = mkEnableOption (lib.mdDoc "nushell"); package = mkOption { type = types.package; default = pkgs.nushell; defaultText = literalExpression "pkgs.nushell"; - description = "The package to use for nushell."; + description = lib.mdDoc "The package to use for nushell."; }; configFile = mkOption { @@ -74,11 +74,10 @@ in { '''; } ''; - description = '' + description = lib.mdDoc '' The configuration file to be used for nushell. - - - See for more information. + + See for more information. ''; }; @@ -88,11 +87,10 @@ in { example = '' let-env FOO = 'BAR' ''; - description = '' + description = lib.mdDoc '' The environment variables file to be used for nushell. - - - See for more information. + + See for more information. ''; }; @@ -105,18 +103,17 @@ in { echo "Hello, World" } ''; - description = '' + description = lib.mdDoc '' The login file to be used for nushell upon logging in. - - - See for more information. + + See for more information. ''; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional configuration to add to the nushell configuration file. ''; }; @@ -124,7 +121,7 @@ in { extraEnv = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional configuration to add to the nushell environment variables file. ''; }; @@ -132,7 +129,7 @@ in { extraLogin = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional configuration to add to the nushell login file. ''; }; @@ -141,7 +138,7 @@ in { type = types.attrsOf types.str; default = { }; example = { ll = "ls -l"; }; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. ''; @@ -151,7 +148,7 @@ in { type = types.attrsOf types.str; default = { }; example = { FOO = "BAR"; }; - description = '' + description = lib.mdDoc '' An attribute set that maps an environment variable to a shell interpreted string. ''; }; diff --git a/modules/programs/obs-studio.nix b/modules/programs/obs-studio.nix index ba5c8919..b8cee836 100644 --- a/modules/programs/obs-studio.nix +++ b/modules/programs/obs-studio.nix @@ -11,13 +11,13 @@ in { options = { programs.obs-studio = { - enable = mkEnableOption "obs-studio"; + enable = mkEnableOption (lib.mdDoc "obs-studio"); package = mkOption { type = types.package; default = pkgs.obs-studio; defaultText = literalExpression "pkgs.obs-studio"; - description = '' + description = lib.mdDoc '' OBS Studio package to install. ''; }; @@ -26,13 +26,13 @@ in { type = types.package; visible = false; readOnly = true; - description = "Resulting customized OBS Studio package."; + description = lib.mdDoc "Resulting customized OBS Studio package."; }; plugins = mkOption { default = [ ]; example = literalExpression "[ pkgs.obs-studio-plugins.wlrobs ]"; - description = "Optional OBS plugins."; + description = lib.mdDoc "Optional OBS plugins."; type = types.listOf types.package; }; }; diff --git a/modules/programs/octant.nix b/modules/programs/octant.nix index f3b810c9..e61c9b99 100644 --- a/modules/programs/octant.nix +++ b/modules/programs/octant.nix @@ -23,20 +23,20 @@ in { options = { programs.octant = { - enable = mkEnableOption "octant"; + enable = mkEnableOption (lib.mdDoc "octant"); package = mkOption { type = types.package; default = pkgs.octant; defaultText = literalExpression "pkgs.octant"; example = literalExpression "pkgs.octant-other"; - description = "The Octant package to use."; + description = lib.mdDoc "The Octant package to use."; }; plugins = mkOption { default = [ ]; example = literalExpression "[ pkgs.starboard-octant-plugin ]"; - description = "Optional Octant plugins."; + description = lib.mdDoc "Optional Octant plugins."; type = types.listOf types.package; }; }; diff --git a/modules/programs/offlineimap-accounts.nix b/modules/programs/offlineimap-accounts.nix index afc7a019..a4f3a85c 100644 --- a/modules/programs/offlineimap-accounts.nix +++ b/modules/programs/offlineimap-accounts.nix @@ -8,13 +8,13 @@ let in { options.offlineimap = { - enable = mkEnableOption "OfflineIMAP"; + enable = mkEnableOption (lib.mdDoc "OfflineIMAP"); extraConfig.account = mkOption { type = extraConfigType; default = { }; example = { autorefresh = 20; }; - description = '' + description = lib.mdDoc '' Extra configuration options to add to the account section. ''; }; @@ -23,7 +23,7 @@ in { type = extraConfigType; default = { }; example = { sync_deletes = true; }; - description = '' + description = lib.mdDoc '' Extra configuration options to add to the local account section. ''; @@ -36,7 +36,7 @@ in { maxconnections = 2; expunge = false; }; - description = '' + description = lib.mdDoc '' Extra configuration options to add to the remote account section. ''; @@ -45,7 +45,7 @@ in { postSyncHookCommand = mkOption { type = types.lines; default = ""; - description = "Command to run after fetching new mails."; + description = lib.mdDoc "Command to run after fetching new mails."; }; }; } diff --git a/modules/programs/offlineimap.nix b/modules/programs/offlineimap.nix index 439c40d4..2927333d 100644 --- a/modules/programs/offlineimap.nix +++ b/modules/programs/offlineimap.nix @@ -88,7 +88,7 @@ let in { options = { programs.offlineimap = { - enable = mkEnableOption "OfflineIMAP"; + enable = mkEnableOption (lib.mdDoc "OfflineIMAP"); package = mkPackageOptionMD pkgs "offlineimap" { example = '' @@ -108,7 +108,7 @@ in { def get_pass(service, cmd): return subprocess.check_output(cmd, ) ''; - description = '' + description = lib.mdDoc '' Python code that can then be used in other parts of the configuration. ''; @@ -121,9 +121,9 @@ in { maxage = 30; ui = "blinkenlights"; }; - description = '' + description = lib.mdDoc '' Extra configuration options added to the - section. + {option}`general` section. ''; }; @@ -131,9 +131,9 @@ in { type = extraConfigType; default = { }; example = { gmailtrashfolder = "[Gmail]/Papierkorb"; }; - description = '' + description = lib.mdDoc '' Extra configuration options added to the - section. + {option}`DEFAULT` section. ''; }; @@ -149,9 +149,9 @@ in { footer = "'\\n'"; } ''; - description = '' + description = lib.mdDoc '' Extra configuration options added to the - mbnames section. + `mbnames` section. ''; }; }; diff --git a/modules/programs/oh-my-posh.nix b/modules/programs/oh-my-posh.nix index a6b07701..63d38878 100644 --- a/modules/programs/oh-my-posh.nix +++ b/modules/programs/oh-my-posh.nix @@ -18,7 +18,8 @@ in { meta.maintainers = [ maintainers.arjan-s ]; options.programs.oh-my-posh = { - enable = mkEnableOption "oh-my-posh, a prompt theme engine for any shell"; + enable = mkEnableOption + (lib.mdDoc "oh-my-posh, a prompt theme engine for any shell"); package = mkPackageOptionMD pkgs "oh-my-posh" { }; @@ -27,11 +28,11 @@ in { default = { }; example = literalExpression '' builtins.fromJSON (builtins.unsafeDiscardStringContext (builtins.readFile "''${pkgs.oh-my-posh}/share/oh-my-posh/themes/space.omp.json"))''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/oh-my-posh/config.json. See - - for details. The useTheme option is ignored when this + {file}`$XDG_CONFIG_HOME/oh-my-posh/config.json`. See + + for details. The `useTheme` option is ignored when this option is used. ''; }; @@ -39,18 +40,18 @@ in { useTheme = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Use one of the official themes. This should be a name from this list: - . Because a theme + . Because a theme is essentially a configuration file, this option is not used when a - configFile is set. + `configFile` is set. ''; }; enableBashIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -58,7 +59,7 @@ in { enableZshIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -66,7 +67,7 @@ in { enableFishIntegration = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/opam.nix b/modules/programs/opam.nix index 34338514..7f139f6e 100644 --- a/modules/programs/opam.nix +++ b/modules/programs/opam.nix @@ -10,19 +10,19 @@ in { meta.maintainers = [ ]; options.programs.opam = { - enable = mkEnableOption "Opam"; + enable = mkEnableOption (lib.mdDoc "Opam"); package = mkOption { type = types.package; default = pkgs.opam; defaultText = literalExpression "pkgs.opam"; - description = "Opam package to install."; + description = lib.mdDoc "Opam package to install."; }; enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -30,7 +30,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -38,7 +38,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/pandoc.nix b/modules/programs/pandoc.nix index 7f0fa713..5a2858c1 100644 --- a/modules/programs/pandoc.nix +++ b/modules/programs/pandoc.nix @@ -22,20 +22,20 @@ in { meta.maintainers = [ lib.maintainers.kirelagin ]; options.programs.pandoc = { - enable = mkEnableOption "pandoc"; + enable = mkEnableOption (lib.mdDoc "pandoc"); package = mkOption { type = types.package; default = pkgs.pandoc; defaultText = literalExpression "pkgs.pandoc"; - description = "The pandoc package to use."; + description = lib.mdDoc "The pandoc package to use."; }; # We wrap the executable to pass some arguments finalPackage = mkOption { type = types.package; readOnly = true; - description = "Resulting package."; + description = lib.mdDoc "Resulting package."; }; defaults = mkOption { @@ -50,7 +50,7 @@ in { citeproc = true; } ''; - description = '' + description = lib.mdDoc '' Options to set by default. These will be converted to JSON and written to a defaults file (see Default files in pandoc documentation). @@ -60,7 +60,7 @@ in { defaultsFile = mkOption { type = types.path; readOnly = true; - description = "Resulting defaults file."; + description = lib.mdDoc "Resulting defaults file."; }; templates = mkOption { @@ -71,14 +71,14 @@ in { "default.latex" = path/to/your/template; } ''; - description = "Custom templates."; + description = lib.mdDoc "Custom templates."; }; citationStyles = mkOption { type = types.listOf types.path; default = [ ]; example = literalExpression "[ path/to/file.csl ]"; - description = "List of .csl files to install."; + description = lib.mdDoc "List of .csl files to install."; }; }; diff --git a/modules/programs/papis.nix b/modules/programs/papis.nix index 69d1db34..4611b66d 100644 --- a/modules/programs/papis.nix +++ b/modules/programs/papis.nix @@ -17,7 +17,7 @@ in { meta.maintainers = [ ]; options.programs.papis = { - enable = mkEnableOption "papis"; + enable = mkEnableOption (lib.mdDoc "papis"); settings = mkOption { type = with types; attrsOf (oneOf [ bool int str ]); @@ -29,10 +29,10 @@ in { add-edit = true; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/papis/config. See - + {file}`$XDG_CONFIG_HOME/papis/config`. See + for supported values. ''; }; @@ -44,14 +44,14 @@ in { type = types.str; default = name; readOnly = true; - description = "This library's name."; + description = lib.mdDoc "This library's name."; }; isDefault = mkOption { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether this is a default library. There must be exactly one default library. ''; @@ -65,13 +65,13 @@ in { dir = "~/papers/"; } ''; - description = '' + description = lib.mdDoc '' Configuration for this library. ''; }; }; })); - description = "Attribute set of papis libraries."; + description = lib.mdDoc "Attribute set of papis libraries."; }; }; diff --git a/modules/programs/password-store.nix b/modules/programs/password-store.nix index 076db93e..806949fe 100644 --- a/modules/programs/password-store.nix +++ b/modules/programs/password-store.nix @@ -10,7 +10,7 @@ in { meta.maintainers = with maintainers; [ pacien ]; options.programs.password-store = { - enable = mkEnableOption "Password store"; + enable = mkEnableOption (lib.mdDoc "Password store"); package = mkOption { type = types.package; @@ -19,8 +19,8 @@ in { example = literalExpression '' pkgs.pass.withExtensions (exts: [ exts.pass-otp ]) ''; - description = '' - The pass package to use. + description = lib.mdDoc '' + The `pass` package to use. Can be used to specify extensions. ''; }; @@ -41,14 +41,11 @@ in { PASSWORD_STORE_CLIP_TIME = "60"; } ''; - description = '' - The pass environment variables dictionary. - + description = lib.mdDoc '' + The `pass` environment variables dictionary. + See the "Environment variables" section of - - pass - 1 - + {manpage}`pass(1)` and the extension man pages for more information about the available keys. ''; diff --git a/modules/programs/pazi.nix b/modules/programs/pazi.nix index 9e603df2..46457b00 100644 --- a/modules/programs/pazi.nix +++ b/modules/programs/pazi.nix @@ -10,12 +10,12 @@ in { meta.maintainers = [ ]; options.programs.pazi = { - enable = mkEnableOption "pazi"; + enable = mkEnableOption (lib.mdDoc "pazi"); enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -23,7 +23,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -31,7 +31,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/pet.nix b/modules/programs/pet.nix index 48e972ae..97fbbdda 100644 --- a/modules/programs/pet.nix +++ b/modules/programs/pet.nix @@ -14,7 +14,7 @@ let type = types.str; default = ""; example = "Count the number of commits in the current branch"; - description = '' + description = lib.mdDoc '' Description of the snippet. ''; }; @@ -23,7 +23,7 @@ let type = types.str; default = ""; example = "git rev-list --count HEAD"; - description = '' + description = lib.mdDoc '' The command. ''; }; @@ -32,7 +32,7 @@ let type = types.str; default = ""; example = "473"; - description = '' + description = lib.mdDoc '' Example output of the command. ''; }; @@ -41,7 +41,7 @@ let type = types.listOf types.str; default = [ ]; example = literalExpression ''["git" "nixpkgs"]''; - description = '' + description = lib.mdDoc '' List of tags attached to the command. ''; }; @@ -50,13 +50,13 @@ let in { options.programs.pet = { - enable = mkEnableOption "pet"; + enable = mkEnableOption (lib.mdDoc "pet"); settings = mkOption { type = format.type; default = { }; - description = '' - Settings written to config.toml. See the pet + description = lib.mdDoc '' + Settings written to {file}`config.toml`. See the pet documentation for details. ''; }; @@ -65,15 +65,15 @@ in { type = types.package; default = pkgs.fzf; defaultText = literalExpression "pkgs.fzf"; - description = '' - The package needed for the settings.selectcmd. + description = lib.mdDoc '' + The package needed for the {var}`settings.selectcmd`. ''; }; snippets = mkOption { type = types.listOf snippetType; default = [ ]; - description = '' + description = lib.mdDoc '' The snippets. ''; }; diff --git a/modules/programs/pidgin.nix b/modules/programs/pidgin.nix index d7536be7..93f86c3f 100644 --- a/modules/programs/pidgin.nix +++ b/modules/programs/pidgin.nix @@ -11,19 +11,19 @@ in { options = { programs.pidgin = { - enable = mkEnableOption "Pidgin messaging client"; + enable = mkEnableOption (lib.mdDoc "Pidgin messaging client"); package = mkOption { type = types.package; default = pkgs.pidgin; defaultText = literalExpression "pkgs.pidgin"; - description = "The Pidgin package to use."; + description = lib.mdDoc "The Pidgin package to use."; }; plugins = mkOption { default = [ ]; example = literalExpression "[ pkgs.pidgin-otr pkgs.pidgin-osd ]"; - description = "Plugins that should be available to Pidgin."; + description = lib.mdDoc "Plugins that should be available to Pidgin."; }; }; }; diff --git a/modules/programs/pistol.nix b/modules/programs/pistol.nix index 4d6a1d29..384f63a3 100644 --- a/modules/programs/pistol.nix +++ b/modules/programs/pistol.nix @@ -13,19 +13,22 @@ let options = { command = mkOption { type = types.str; - description = "Preview command for files matched by this association."; + description = + lib.mdDoc "Preview command for files matched by this association."; }; fpath = mkOption { type = types.str; default = ""; - description = "File path regex that this association should match."; + description = + lib.mdDoc "File path regex that this association should match."; }; mime = mkOption { type = types.str; default = ""; - description = "Mime type regex that this association should match."; + description = + lib.mdDoc "Mime type regex that this association should match."; }; }; }; @@ -38,7 +41,8 @@ in { meta.maintainers = [ hm.maintainers.mtoohey ]; options.programs.pistol = { - enable = mkEnableOption "file previewer for terminal file managers"; + enable = + mkEnableOption (lib.mdDoc "file previewer for terminal file managers"); associations = mkOption { type = types.listOf association; @@ -50,9 +54,9 @@ in { { fpath = ".*.md$"; command = "sh: bat --paging=never --color=always %pistol-filename% | head -8"; } ] ''; - description = '' + description = lib.mdDoc '' Associations written to the Pistol configuration at - $XDG_CONFIG_HOME/pistol/pistol.conf. + {file}`$XDG_CONFIG_HOME/pistol/pistol.conf`. ''; }; diff --git a/modules/programs/piston-cli.nix b/modules/programs/piston-cli.nix index 6315cb5c..ca485bf5 100644 --- a/modules/programs/piston-cli.nix +++ b/modules/programs/piston-cli.nix @@ -9,13 +9,13 @@ in { meta.maintainers = with maintainers; [ ethancedwards8 ]; options.programs.piston-cli = { - enable = mkEnableOption "piston-cli, code runner"; + enable = mkEnableOption (lib.mdDoc "piston-cli, code runner"); package = mkOption { type = types.package; default = pkgs.piston-cli; defaultText = literalExpression "pkgs.piston-cli"; - description = "The piston-cli package to use."; + description = lib.mdDoc "The piston-cli package to use."; }; settings = mkOption { @@ -29,9 +29,9 @@ in { prompt_start = ">>>"; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/piston-cli/config.yml. + {file}`$XDG_CONFIG_HOME/piston-cli/config.yml`. ''; }; }; diff --git a/modules/programs/pls.nix b/modules/programs/pls.nix index 47216d4e..332d2738 100644 --- a/modules/programs/pls.nix +++ b/modules/programs/pls.nix @@ -17,11 +17,11 @@ in { options.programs.pls = { enable = - mkEnableOption "pls, a modern replacement for ls"; + mkEnableOption (lib.mdDoc "pls, a modern replacement for {command}`ls`"); package = mkPackageOptionMD pkgs "pls" { }; - enableAliases = mkEnableOption "recommended pls aliases"; + enableAliases = mkEnableOption (lib.mdDoc "recommended pls aliases"); }; config = mkIf cfg.enable { diff --git a/modules/programs/powerline-go.nix b/modules/programs/powerline-go.nix index ec4e45c2..6ddb0aa9 100644 --- a/modules/programs/powerline-go.nix +++ b/modules/programs/powerline-go.nix @@ -49,16 +49,16 @@ in { options = { programs.powerline-go = { - enable = mkEnableOption - "Powerline-go, a beautiful and useful low-latency prompt for your shell"; + enable = mkEnableOption (lib.mdDoc + "Powerline-go, a beautiful and useful low-latency prompt for your shell"); modules = mkOption { default = null; type = types.nullOr (types.listOf types.str); - description = '' + description = lib.mdDoc '' List of module names to load. The list of all available modules as well as the choice of default ones are at - . + . ''; example = [ "host" "ssh" "cwd" "gitlite" "jobs" "exit" ]; }; @@ -66,7 +66,7 @@ in { modulesRight = mkOption { default = null; type = types.nullOr (types.listOf types.str); - description = '' + description = lib.mdDoc '' List of module names to load to be displayed on the right side. Currently not supported by bash. Specifying a value for this option will force powerline-go to use the eval format to set @@ -78,7 +78,7 @@ in { newline = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Set to true if the prompt should be on a line of its own. ''; example = true; @@ -87,7 +87,7 @@ in { pathAliases = mkOption { default = null; type = types.nullOr (types.attrsOf types.str); - description = '' + description = lib.mdDoc '' Pairs of full-path and corresponding desired short name. You may use '~' to represent your home directory but you should protect it to avoid shell substitution. @@ -100,9 +100,9 @@ in { settings = mkOption { default = { }; type = with types; attrsOf (oneOf [ bool int str (listOf str) ]); - description = '' + description = lib.mdDoc '' This can be any key/value pair as described in - . + . ''; example = literalExpression '' { @@ -116,7 +116,8 @@ in { extraUpdatePS1 = mkOption { default = ""; - description = "Shell code to execute after the prompt is set."; + description = + lib.mdDoc "Shell code to execute after the prompt is set."; example = '' PS1=$PS1"NixOS> "; ''; diff --git a/modules/programs/pubs.nix b/modules/programs/pubs.nix index 5a597dea..62c996d6 100644 --- a/modules/programs/pubs.nix +++ b/modules/programs/pubs.nix @@ -10,13 +10,13 @@ in { meta.maintainers = [ hm.maintainers.loicreynier ]; options.programs.pubs = { - enable = mkEnableOption "pubs"; + enable = mkEnableOption (lib.mdDoc "pubs"); package = mkOption { type = types.package; default = pkgs.pubs; defaultText = literalExpression "pkgs.pubs"; - description = "The package to use for the pubs script."; + description = lib.mdDoc "The package to use for the pubs script."; }; extraConfig = mkOption { @@ -44,9 +44,9 @@ in { manual = False force_color = False '''''; - description = '' + description = lib.mdDoc '' Configuration using syntax written to - $HOME/.pubsrc. + {file}`$HOME/.pubsrc`. ''; }; }; diff --git a/modules/programs/pyenv.nix b/modules/programs/pyenv.nix index 5ff0a83a..20b9a37c 100644 --- a/modules/programs/pyenv.nix +++ b/modules/programs/pyenv.nix @@ -10,19 +10,19 @@ in { meta.maintainers = with lib.maintainers; [ tmarkus ]; options.programs.pyenv = { - enable = lib.mkEnableOption "pyenv"; + enable = lib.mkEnableOption (lib.mdDoc "pyenv"); package = lib.mkOption { type = lib.types.package; default = pkgs.pyenv; defaultText = lib.literalExpression "pkgs.pyenv"; - description = "The package to use for pyenv."; + description = lib.mdDoc "The package to use for pyenv."; }; enableBashIntegration = lib.mkOption { type = lib.types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable pyenv's Bash integration. ''; }; @@ -30,7 +30,7 @@ in { enableZshIntegration = lib.mkOption { type = lib.types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable pyenv's Zsh integration. ''; }; @@ -38,7 +38,7 @@ in { enableFishIntegration = lib.mkOption { type = lib.types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable pyenv's Fish integration. ''; }; diff --git a/modules/programs/pylint.nix b/modules/programs/pylint.nix index e6679b98..4c184de7 100644 --- a/modules/programs/pylint.nix +++ b/modules/programs/pylint.nix @@ -10,18 +10,18 @@ let in { meta.maintainers = [ hm.maintainers.florpe ]; options.programs.pylint = { - enable = mkEnableOption "the pylint Python linter"; + enable = mkEnableOption (lib.mdDoc "the pylint Python linter"); package = mkOption { type = types.package; default = pkgs.python3Packages.pylint; defaultText = literalExpression "pkgs.python3Packages.pylint"; - description = "The pylint package to use."; + description = lib.mdDoc "The pylint package to use."; }; settings = mkOption { type = iniFormat.type; default = { }; defaultText = literalExpression "{}"; - description = "The pylint configuration."; + description = lib.mdDoc "The pylint configuration."; }; }; config = mkIf cfg.enable { diff --git a/modules/programs/pywal.nix b/modules/programs/pywal.nix index b32f087c..642b8ffd 100644 --- a/modules/programs/pywal.nix +++ b/modules/programs/pywal.nix @@ -5,7 +5,9 @@ with lib; let cfg = config.programs.pywal; in { - options = { programs.pywal = { enable = mkEnableOption "pywal"; }; }; + options = { + programs.pywal = { enable = mkEnableOption (lib.mdDoc "pywal"); }; + }; config = mkIf cfg.enable { diff --git a/modules/programs/qutebrowser.nix b/modules/programs/qutebrowser.nix index e3c17cc3..44b49fe7 100644 --- a/modules/programs/qutebrowser.nix +++ b/modules/programs/qutebrowser.nix @@ -36,19 +36,19 @@ let in { options.programs.qutebrowser = { - enable = mkEnableOption "qutebrowser"; + enable = mkEnableOption (lib.mdDoc "qutebrowser"); package = mkOption { type = types.package; default = pkgs.qutebrowser; defaultText = literalExpression "pkgs.qutebrowser"; - description = "Qutebrowser package to install."; + description = lib.mdDoc "Qutebrowser package to install."; }; aliases = mkOption { type = types.attrsOf types.str; default = { }; - description = '' + description = lib.mdDoc '' Aliases for commands. ''; }; @@ -56,7 +56,7 @@ in { loadAutoconfig = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Load settings configured via the GUI. ''; }; @@ -64,18 +64,18 @@ in { searchEngines = mkOption { type = types.attrsOf types.str; default = { }; - description = '' + description = lib.mdDoc '' Search engines that can be used via the address bar. Maps a search - engine name (such as DEFAULT, or - ddg) to a URL with a {} + engine name (such as `DEFAULT`, or + `ddg`) to a URL with a `{}` placeholder. The placeholder will be replaced by the search term, use - {{ and }} for literal - {/} signs. The search engine named - DEFAULT is used when - url.auto_search is turned on and something else than + `{{` and `}}` for literal + `{/}` signs. The search engine named + `DEFAULT` is used when + `url.auto_search` is turned on and something else than a URL was entered to be opened. Other search engines can be used by prepending the search engine name to the search term, for example - :open google qutebrowser. + `:open google qutebrowser`. ''; example = literalExpression '' { @@ -90,9 +90,9 @@ in { settings = mkOption { type = types.attrsOf types.anything; default = { }; - description = '' - Options to add to qutebrowser config.py file. - See + description = lib.mdDoc '' + Options to add to qutebrowser {file}`config.py` file. + See for options. ''; example = literalExpression '' @@ -112,20 +112,20 @@ in { keyMappings = mkOption { type = types.attrsOf types.str; default = { }; - description = '' + description = lib.mdDoc '' This setting can be used to map keys to other keys. When the key used as dictionary-key is pressed, the binding for the key used as dictionary-value is invoked instead. This is useful for global remappings of keys, for example to map Ctrl-[ to Escape. Note that when - a key is bound (via bindings.default or - bindings.commands), the mapping is ignored. + a key is bound (via `bindings.default` or + `bindings.commands`), the mapping is ignored. ''; }; enableDefaultBindings = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Disable to prevent loading default key bindings. ''; }; @@ -227,8 +227,8 @@ in { quickmarks = mkOption { type = types.attrsOf types.str; default = { }; - description = '' - Quickmarks to add to qutebrowser's quickmarks file. + description = lib.mdDoc '' + Quickmarks to add to qutebrowser's {file}`quickmarks` file. Note that when Home Manager manages your quickmarks, you cannot edit them at runtime. ''; example = literalExpression '' @@ -242,8 +242,8 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra lines added to qutebrowser config.py file. + description = lib.mdDoc '' + Extra lines added to qutebrowser {file}`config.py` file. ''; }; }; diff --git a/modules/programs/rbenv.nix b/modules/programs/rbenv.nix index 49c454e2..33ebc74c 100644 --- a/modules/programs/rbenv.nix +++ b/modules/programs/rbenv.nix @@ -10,13 +10,13 @@ let options = { src = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to the plugin folder. ''; }; name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Name of the plugin. ''; }; @@ -27,7 +27,7 @@ in { meta.maintainers = [ ]; options.programs.rbenv = { - enable = mkEnableOption "rbenv"; + enable = mkEnableOption (lib.mdDoc "rbenv"); package = mkPackageOptionMD pkgs "rbenv" { }; @@ -47,23 +47,23 @@ in { } ] ''; - description = '' - rbenv plugins to install in $HOME/.rbenv/plugins/. - - See + description = lib.mdDoc '' + rbenv plugins to install in {file}`$HOME/.rbenv/plugins/`. + + See for the full list of plugins. ''; }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = true; }; - enableFishIntegration = mkEnableOption "Fish integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish integration") // { default = true; }; }; diff --git a/modules/programs/rbw.nix b/modules/programs/rbw.nix index 204aaa6b..977490ac 100644 --- a/modules/programs/rbw.nix +++ b/modules/programs/rbw.nix @@ -13,7 +13,8 @@ let email = mkOption { type = types.str; example = "name@example.com"; - description = "The email address for your bitwarden account."; + description = + lib.mdDoc "The email address for your bitwarden account."; }; base_url = mkOption { @@ -21,21 +22,22 @@ let default = null; example = "bitwarden.example.com"; description = - "The base-url for a self-hosted bitwarden installation."; + lib.mdDoc "The base-url for a self-hosted bitwarden installation."; }; identity_url = mkOption { type = with types; nullOr str; default = null; example = "identity.example.com"; - description = "The identity url for your bitwarden installation."; + description = + lib.mdDoc "The identity url for your bitwarden installation."; }; lock_timeout = mkOption { type = types.ints.unsigned; default = 3600; example = 300; - description = '' + description = lib.mdDoc '' The amount of time that your login information should be cached. ''; }; @@ -44,15 +46,15 @@ let type = with types; either package (enum pkgs.pinentry.flavors); example = "gnome3"; default = "gtk2"; - description = '' + description = lib.mdDoc '' Which pinentry interface to use. Beware that - pinentry-gnome3 may not work on non-Gnome + `pinentry-gnome3` may not work on non-Gnome systems. You can fix it by adding the following to your system configuration: - + ```nix services.dbus.packages = [ pkgs.gcr ]; - - For this reason, the default is gtk2 for + ``` + For this reason, the default is `gtk2` for now. ''; # we want the program in the config @@ -68,15 +70,15 @@ in { meta.maintainers = with lib.hm.maintainers; [ ambroisie ]; options.programs.rbw = with lib; { - enable = mkEnableOption "rbw, a CLI Bitwarden client"; + enable = mkEnableOption (lib.mdDoc "rbw, a CLI Bitwarden client"); package = mkOption { type = types.package; default = pkgs.rbw; defaultText = literalExpression "pkgs.rbw"; - description = '' - Package providing the rbw tool and its - rbw-agent daemon. + description = lib.mdDoc '' + Package providing the {command}`rbw` tool and its + {command}`rbw-agent` daemon. ''; }; @@ -90,7 +92,7 @@ in { pinentry = "gnome3"; } ''; - description = '' + description = lib.mdDoc '' rbw configuration, if not defined the configuration will not be managed by Home Manager. ''; diff --git a/modules/programs/readline.nix b/modules/programs/readline.nix index fecb4572..f23c27c3 100644 --- a/modules/programs/readline.nix +++ b/modules/programs/readline.nix @@ -32,7 +32,7 @@ let in { options.programs.readline = { - enable = mkEnableOption "readline"; + enable = mkEnableOption (lib.mdDoc "readline"); bindings = mkOption { default = { }; @@ -40,14 +40,14 @@ in { example = literalExpression '' { "\\C-h" = "backward-kill-word"; } ''; - description = "Readline bindings."; + description = lib.mdDoc "Readline bindings."; }; variables = mkOption { type = with types; attrsOf (either str (either int bool)); default = { }; example = { expand-tilde = true; }; - description = '' + description = lib.mdDoc '' Readline customization variable assignments. ''; }; @@ -55,15 +55,16 @@ in { includeSystemConfig = mkOption { type = types.bool; default = true; - description = "Whether to include the system-wide configuration."; + description = + lib.mdDoc "Whether to include the system-wide configuration."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration lines appended unchanged to the end of the - ~/.inputrc file. + {file}`~/.inputrc` file. ''; }; }; diff --git a/modules/programs/ripgrep.nix b/modules/programs/ripgrep.nix index f925e6e6..6402b4c5 100644 --- a/modules/programs/ripgrep.nix +++ b/modules/programs/ripgrep.nix @@ -10,7 +10,7 @@ in { options = { programs.ripgrep = { - enable = mkEnableOption "Ripgrep"; + enable = mkEnableOption (lib.mdDoc "Ripgrep"); package = mkPackageOptionMD pkgs "ripgrep" { }; @@ -18,11 +18,11 @@ in { type = with types; listOf str; default = [ ]; example = [ "--max-columns-preview" "--colors=line:style:bold" ]; - description = '' + description = lib.mdDoc '' List of arguments to pass to ripgrep. Each item is given to ripgrep as a single command line argument verbatim. - - See + + See for an example configuration. ''; }; diff --git a/modules/programs/rofi-pass.nix b/modules/programs/rofi-pass.nix index da75299e..e45d77b9 100644 --- a/modules/programs/rofi-pass.nix +++ b/modules/programs/rofi-pass.nix @@ -10,12 +10,12 @@ in { meta.maintainers = [ maintainers.seylerius ]; options.programs.rofi.pass = { - enable = mkEnableOption "rofi integration with password-store"; + enable = mkEnableOption (lib.mdDoc "rofi integration with password-store"); stores = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' Directory roots of your password-stores. ''; }; @@ -28,10 +28,10 @@ in { USERNAME_field='user' AUTOTYPE_field='autotype' ''; - description = '' + description = lib.mdDoc '' Extra configuration to be added at to the rofi-pass config file. Additional examples can be found at - . + . ''; }; }; diff --git a/modules/programs/rofi.nix b/modules/programs/rofi.nix index 8b1fc991..80622b0e 100644 --- a/modules/programs/rofi.nix +++ b/modules/programs/rofi.nix @@ -101,14 +101,14 @@ let in { options.programs.rofi = { - enable = mkEnableOption - "Rofi: A window switcher, application launcher and dmenu replacement"; + enable = mkEnableOption (lib.mdDoc + "Rofi: A window switcher, application launcher and dmenu replacement"); package = mkOption { default = pkgs.rofi; type = types.package; - description = '' - Package providing the rofi binary. + description = lib.mdDoc '' + Package providing the {command}`rofi` binary. ''; example = literalExpression '' pkgs.rofi.override { plugins = [ pkgs.rofi-emoji ]; }; @@ -118,7 +118,7 @@ in { finalPackage = mkOption { type = types.package; readOnly = true; - description = '' + description = lib.mdDoc '' Resulting customized rofi package. ''; }; @@ -126,7 +126,7 @@ in { plugins = mkOption { default = [ ]; type = types.listOf types.package; - description = '' + description = lib.mdDoc '' List of rofi plugins to be installed. ''; example = literalExpression "[ pkgs.rofi-calc ]"; @@ -136,13 +136,13 @@ in { default = null; type = types.nullOr types.str; example = "Droid Sans Mono 14"; - description = "Font to use."; + description = lib.mdDoc "Font to use."; }; terminal = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Path to the terminal which will be used to run console applications ''; example = "\${pkgs.gnome.gnome_terminal}/bin/gnome-terminal"; @@ -151,19 +151,19 @@ in { cycle = mkOption { default = null; type = types.nullOr types.bool; - description = "Whether to cycle through the results list."; + description = lib.mdDoc "Whether to cycle through the results list."; }; location = mkOption { default = "center"; type = types.enum (attrNames locationsMap); - description = "The location rofi appears on the screen."; + description = lib.mdDoc "The location rofi appears on the screen."; }; xoffset = mkOption { default = 0; type = types.int; - description = '' + description = lib.mdDoc '' Offset in the x-axis in pixels relative to the chosen location. ''; }; @@ -171,7 +171,7 @@ in { yoffset = mkOption { default = 0; type = types.int; - description = '' + description = lib.mdDoc '' Offset in the y-axis in pixels relative to the chosen location. ''; }; @@ -208,10 +208,10 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Name of theme or path to theme file in rasi format or attribute set with theme configuration. Available named themes can be viewed using the - rofi-theme-selector tool. + {command}`rofi-theme-selector` tool. ''; }; @@ -219,7 +219,7 @@ in { default = "${config.xdg.configHome}/rofi/config.rasi"; defaultText = "$XDG_CONFIG_HOME/rofi/config.rasi"; type = types.str; - description = "Path where to put generated configuration file."; + description = lib.mdDoc "Path where to put generated configuration file."; }; extraConfig = mkOption { @@ -232,7 +232,7 @@ in { } ''; type = configType; - description = "Additional configuration to add."; + description = lib.mdDoc "Additional configuration to add."; }; }; diff --git a/modules/programs/rtorrent.nix b/modules/programs/rtorrent.nix index 7736596e..922a5d32 100644 --- a/modules/programs/rtorrent.nix +++ b/modules/programs/rtorrent.nix @@ -16,15 +16,15 @@ in { ]; options.programs.rtorrent = { - enable = mkEnableOption "rTorrent"; + enable = mkEnableOption (lib.mdDoc "rTorrent"); extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/rtorrent/rtorrent.rc. See - + {file}`$XDG_CONFIG_HOME/rtorrent/rtorrent.rc`. See + for explanation about possible values. ''; }; diff --git a/modules/programs/rtx.nix b/modules/programs/rtx.nix index 7400448e..ea2e9160 100644 --- a/modules/programs/rtx.nix +++ b/modules/programs/rtx.nix @@ -10,19 +10,20 @@ in { options = { programs.rtx = { - enable = mkEnableOption "RTX. Runtime Executor (asdf Rust clone)"; + enable = + mkEnableOption (lib.mdDoc "RTX. Runtime Executor (asdf Rust clone)"); package = mkPackageOptionMD pkgs "rtx" { }; - enableBashIntegration = mkEnableOption "Bash Integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash Integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh Integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh Integration") // { default = true; }; - enableFishIntegration = mkEnableOption "Fish Integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish Integration") // { default = true; }; @@ -40,16 +41,16 @@ in { experimental = false; }; ''; - description = '' - Settings written to $XDG_CONFIG_HOME/rtx/config.toml. + description = lib.mdDoc '' + Settings written to {file}`$XDG_CONFIG_HOME/rtx/config.toml`. - See + See for details on supported values. - - Modifying the tools section doesn't make RTX install them. - You have to manually run rtx install to install the tools. - + ::: {.warning} + Modifying the `tools` section doesn't make RTX install them. + You have to manually run `rtx install` to install the tools. + ::: ''; }; }; diff --git a/modules/programs/sagemath.nix b/modules/programs/sagemath.nix index b07cec10..46df69ab 100644 --- a/modules/programs/sagemath.nix +++ b/modules/programs/sagemath.nix @@ -10,22 +10,23 @@ in { meta.maintainers = [ lib.maintainers.kirelagin ]; options.programs.sagemath = { - enable = mkEnableOption "SageMath, a mathematics software system"; + enable = + mkEnableOption (lib.mdDoc "SageMath, a mathematics software system"); package = mkOption { type = types.package; default = pkgs.sage; defaultText = literalExpression "pkgs.sage"; - description = "The SageMath package to use."; + description = lib.mdDoc "The SageMath package to use."; }; configDir = mkOption { type = types.str; default = "${config.xdg.configHome}/sage"; defaultText = literalExpression "\${config.xdg.configHome}/sage"; - description = '' - Directory where the sage.init file will be stored. - Note that the upstream default is ~/.sage, + description = lib.mdDoc '' + Directory where the {file}`sage.init` file will be stored. + Note that the upstream default is {file}`~/.sage`, but our default is to follow XDG. ''; }; @@ -34,9 +35,9 @@ in { type = types.str; default = "${config.xdg.dataHome}/sage"; defaultText = literalExpression "\${config.xdg.dataHome}/sage"; - description = '' - Location for DOT_SAGE. - Note that the upstream default is ~/.sage, + description = lib.mdDoc '' + Location for {env}`DOT_SAGE`. + Note that the upstream default is {file}`~/.sage`, but our default is to follow XDG. ''; }; @@ -45,8 +46,8 @@ in { type = types.lines; default = ""; example = "%colors linux"; - description = '' - Contents of the init.sage file that is loaded on startup. + description = lib.mdDoc '' + Contents of the {file}`init.sage` file that is loaded on startup. ''; }; }; diff --git a/modules/programs/sbt.nix b/modules/programs/sbt.nix index ce0e73bf..d4ae03f3 100644 --- a/modules/programs/sbt.nix +++ b/modules/programs/sbt.nix @@ -35,17 +35,18 @@ let options = { org = mkOption { type = types.str; - description = "The organization the artifact is published under."; + description = + lib.mdDoc "The organization the artifact is published under."; }; artifact = mkOption { type = types.str; - description = "The name of the artifact."; + description = lib.mdDoc "The name of the artifact."; }; version = mkOption { type = types.str; - description = "The version of the plugin."; + description = lib.mdDoc "The version of the plugin."; }; }; }; @@ -54,23 +55,24 @@ let options = { realm = mkOption { type = types.str; - description = "The realm of the repository you're authenticating to."; + description = + lib.mdDoc "The realm of the repository you're authenticating to."; }; host = mkOption { type = types.str; - description = + description = lib.mdDoc "The hostname of the repository you're authenticating to."; }; user = mkOption { type = types.str; - description = "The user you're using to authenticate."; + description = lib.mdDoc "The user you're using to authenticate."; }; passwordCommand = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The command that provides the password or authentication token for the repository. ''; @@ -90,21 +92,21 @@ in { meta.maintainers = [ maintainers.kubukoz ]; options.programs.sbt = { - enable = mkEnableOption "sbt"; + enable = mkEnableOption (lib.mdDoc "sbt"); package = mkOption { type = types.package; default = pkgs.sbt; defaultText = literalExpression "pkgs.sbt"; - description = "The package with sbt to be installed."; + description = lib.mdDoc "The package with sbt to be installed."; }; baseUserConfigPath = mkOption { type = types.str; default = ".sbt"; - description = '' + description = lib.mdDoc '' Where the sbt configuration files should be located, relative - HOME. + {env}`HOME`. ''; }; @@ -125,7 +127,7 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' A list of plugins to place in the sbt configuration directory. ''; }; @@ -141,7 +143,7 @@ in { passwordCommand = "pass show sbt/user@example.com"; }] ''; - description = '' + description = lib.mdDoc '' A list of credentials to define in the sbt configuration directory. ''; }; @@ -159,28 +161,22 @@ in { "maven-central" ] ''; - description = '' + description = lib.mdDoc '' A list of repositories to use when resolving dependencies. Defined as a list of pre-defined repository or custom repository as a set of name to - URL. The list will be used populate the ~/.sbt/repositories + URL. The list will be used populate the `~/.sbt/repositories` file in the order specified. - - - Pre-defined repositories must be one of local, - maven-local, maven-central. - - + Pre-defined repositories must be one of `local`, + `maven-local`, `maven-central`. Custom repositories are defined as - { name-of-repo = "https://url.to.repo.com"}. - - + `{ name-of-repo = "https://url.to.repo.com"}`. See - + about this configuration section and - + to read about proxy repositories. ''; }; diff --git a/modules/programs/scmpuff.nix b/modules/programs/scmpuff.nix index 0a573af0..af058887 100644 --- a/modules/programs/scmpuff.nix +++ b/modules/programs/scmpuff.nix @@ -5,21 +5,21 @@ in { meta.maintainers = [ maintainers.cpcloud ]; options.programs.scmpuff = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' scmpuff, a command line tool that allows you to work quicker with Git by - substituting numeric shortcuts for files''; + substituting numeric shortcuts for files''); package = mkOption { type = types.package; default = pkgs.scmpuff; defaultText = literalExpression "pkgs.scmpuff"; - description = "Package providing the scmpuff tool."; + description = lib.mdDoc "Package providing the {command}`scmpuff` tool."; }; enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -27,7 +27,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -35,7 +35,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable fish integration. ''; }; diff --git a/modules/programs/script-directory.nix b/modules/programs/script-directory.nix index 2f19a32f..c1eb761b 100644 --- a/modules/programs/script-directory.nix +++ b/modules/programs/script-directory.nix @@ -4,7 +4,7 @@ in { meta.maintainers = [ lib.maintainers.janik ]; options.programs.script-directory = { - enable = lib.mkEnableOption "script-directory"; + enable = lib.mkEnableOption (lib.mdDoc "script-directory"); package = lib.mkPackageOptionMD pkgs "script-directory" { }; diff --git a/modules/programs/senpai.nix b/modules/programs/senpai.nix index 63208071..9d14f48e 100644 --- a/modules/programs/senpai.nix +++ b/modules/programs/senpai.nix @@ -7,12 +7,12 @@ let cfgFmt = pkgs.formats.yaml { }; in { options.programs.senpai = { - enable = mkEnableOption "senpai"; + enable = mkEnableOption (lib.mdDoc "senpai"); package = mkOption { type = types.package; default = pkgs.senpai; defaultText = literalExpression "pkgs.senpai"; - description = "The senpai package to use."; + description = lib.mdDoc "The `senpai` package to use."; }; config = mkOption { type = types.submodule { @@ -20,7 +20,7 @@ in { options = { addr = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The address (host[:port]) of the IRC server. senpai uses TLS connections by default unless you specify no-tls option. TLS connections default to port 6697, plain-text use port 6667. @@ -28,7 +28,7 @@ in { }; nick = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Your nickname, sent with a NICK IRC message. It mustn't contain spaces or colons (:). ''; @@ -36,7 +36,7 @@ in { password = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Your password, used for SASL authentication. Note that it will reside world-readable in the Nix store. ''; @@ -44,7 +44,7 @@ in { no-tls = mkOption { type = types.bool; default = false; - description = "Disables TLS encryption."; + description = lib.mdDoc "Disables TLS encryption."; }; }; }; @@ -55,10 +55,9 @@ in { password = "verysecurepassword"; } ''; - description = '' + description = lib.mdDoc '' Configuration for senpai. For a complete list of options, see - senpai - 5. + {manpage}`senpai(5)`. ''; }; }; diff --git a/modules/programs/sioyek.nix b/modules/programs/sioyek.nix index 4c3ee527..8a5d3d5d 100644 --- a/modules/programs/sioyek.nix +++ b/modules/programs/sioyek.nix @@ -14,22 +14,22 @@ let in { options = { programs.sioyek = { - enable = mkEnableOption - "Sioyek, a PDF viewer designed for reading research papers and technical books"; + enable = mkEnableOption (lib.mdDoc + "Sioyek, a PDF viewer designed for reading research papers and technical books"); package = mkOption { default = pkgs.sioyek; defaultText = literalExpression "pkgs.sioyek"; type = types.package; - description = "Package providing the sioyek binary"; + description = lib.mdDoc "Package providing the sioyek binary"; }; bindings = mkOption { - description = '' + description = lib.mdDoc '' Input configuration written to - $XDG_CONFIG_HOME/sioyek/keys_user.config. - See . - + {file}`$XDG_CONFIG_HOME/sioyek/keys_user.config`. + See . + Each attribute could also accept a list of strings to set multiple bindings of the same command. ''; @@ -48,10 +48,10 @@ in { }; config = mkOption { - description = '' + description = lib.mdDoc '' Input configuration written to - $XDG_CONFIG_HOME/sioyek/prefs_user.config. - See . + {file}`$XDG_CONFIG_HOME/sioyek/prefs_user.config`. + See . ''; type = types.attrsOf types.str; default = { }; diff --git a/modules/programs/skim.nix b/modules/programs/skim.nix index 3d4da74d..fbe200af 100644 --- a/modules/programs/skim.nix +++ b/modules/programs/skim.nix @@ -8,20 +8,20 @@ let in { options.programs.skim = { - enable = mkEnableOption "skim - a command-line fuzzy finder"; + enable = mkEnableOption (lib.mdDoc "skim - a command-line fuzzy finder"); package = mkOption { type = types.package; default = pkgs.skim; defaultText = literalExpression "pkgs.skim"; - description = "Package providing the skim tool."; + description = lib.mdDoc "Package providing the {command}`skim` tool."; }; defaultCommand = mkOption { type = types.nullOr types.str; default = null; example = "fd --type f"; - description = '' + description = lib.mdDoc '' The command that gets executed as the default source for skim when running. ''; @@ -31,7 +31,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--height 40%" "--prompt ⟫" ]; - description = '' + description = lib.mdDoc '' Extra command line options given to skim by default. ''; }; @@ -40,7 +40,7 @@ in { type = types.nullOr types.str; default = null; example = "fd --type f"; - description = '' + description = lib.mdDoc '' The command that gets executed as the source for skim for the CTRL-T keybinding. ''; @@ -50,7 +50,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--preview 'head {}'" ]; - description = '' + description = lib.mdDoc '' Command line options for the CTRL-T keybinding. ''; }; @@ -59,7 +59,7 @@ in { type = types.nullOr types.str; default = null; example = "fd --type d"; - description = '' + description = lib.mdDoc '' The command that gets executed as the source for skim for the ALT-C keybinding. ''; @@ -69,7 +69,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--preview 'tree -C {} | head -200'" ]; - description = '' + description = lib.mdDoc '' Command line options for the ALT-C keybinding. ''; }; @@ -78,7 +78,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--tac" "--exact" ]; - description = '' + description = lib.mdDoc '' Command line options for the CTRL-R keybinding. ''; }; @@ -86,7 +86,7 @@ in { enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -94,7 +94,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -102,7 +102,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; diff --git a/modules/programs/sm64ex.nix b/modules/programs/sm64ex.nix index 48c1cb9b..3d22b51d 100644 --- a/modules/programs/sm64ex.nix +++ b/modules/programs/sm64ex.nix @@ -32,12 +32,12 @@ in { meta.maintainers = [ maintainers.ivar ]; options.programs.sm64ex = { - enable = mkEnableOption "sm64ex"; + enable = mkEnableOption (lib.mdDoc "sm64ex"); package = mkOption { type = types.package; default = pkgs.sm64ex; - description = "The sm64ex package to use."; + description = lib.mdDoc "The sm64ex package to use."; }; region = mkOption { @@ -45,7 +45,7 @@ in { default = null; defaultText = literalExpression "us"; # This is set both in nixpkgs and upstream - description = '' + description = lib.mdDoc '' Your baserom's region. Note that only "us", "eu", and "jp" are supported. ''; example = literalExpression "jp"; @@ -54,7 +54,7 @@ in { baserom = mkOption { type = types.nullOr types.path; default = null; - description = + description = lib.mdDoc "The path to the Super Mario 64 baserom to extract assets from."; example = literalExpression "/home/foo/baserom.us.z64"; }; @@ -62,9 +62,9 @@ in { extraCompileFlags = mkOption { type = with types; nullOr (listOf str); default = null; - description = '' + description = lib.mdDoc '' Extra flags to pass to the compiler. See - + for more information. ''; example = literalExpression '' @@ -79,8 +79,8 @@ in { type = with types; nullOr (attrsOf (either str (either int (either bool (listOf str))))); default = null; - description = - "Settings for sm64ex's $XDG_DATA_HOME/sm64pc/sm64config.txt file."; + description = lib.mdDoc + "Settings for sm64ex's {file}`$XDG_DATA_HOME/sm64pc/sm64config.txt` file."; example = literalExpression '' { fullscreen = false; diff --git a/modules/programs/sqls.nix b/modules/programs/sqls.nix index 2436c020..93e06211 100644 --- a/modules/programs/sqls.nix +++ b/modules/programs/sqls.nix @@ -12,7 +12,8 @@ in { meta.maintainers = [ ]; options.programs.sqls = { - enable = mkEnableOption "sqls, a SQL language server written in Go"; + enable = + mkEnableOption (lib.mdDoc "sqls, a SQL language server written in Go"); settings = mkOption { type = yamlFormat.type; @@ -28,10 +29,10 @@ in { ]; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/sqls/config.yml. See - + {file}`$XDG_CONFIG_HOME/sqls/config.yml`. See + for supported values. ''; }; diff --git a/modules/programs/ssh.nix b/modules/programs/ssh.nix index 50d6e425..e34ea0e4 100644 --- a/modules/programs/ssh.nix +++ b/modules/programs/ssh.nix @@ -26,14 +26,14 @@ let type = types.str; default = "localhost"; example = "example.org"; - description = "The address where to bind the port."; + description = lib.mdDoc "The address where to bind the port."; }; port = mkOption { type = types.nullOr types.port; default = null; example = 8080; - description = "Specifies port number to bind on bind address."; + description = lib.mdDoc "Specifies port number to bind on bind address."; }; }; @@ -50,14 +50,14 @@ let type = types.nullOr types.str; default = null; example = "example.org"; - description = "The address where to forward the traffic to."; + description = lib.mdDoc "The address where to forward the traffic to."; }; port = mkOption { type = types.nullOr types.port; default = null; example = 80; - description = "Specifies port number to forward the traffic to."; + description = lib.mdDoc "Specifies port number to forward the traffic to."; }; }; }; @@ -69,16 +69,13 @@ let type = types.nullOr types.str; default = null; example = "*.example.org"; - description = '' - Host pattern used by this conditional block. + description = lib.mdDoc '' + `Host` pattern used by this conditional block. See - - ssh_config - 5 - - for Host block details. + {manpage}`ssh_config(5)` + for `Host` block details. This option is ignored if - + {option}`ssh.matchBlocks.*.match` if defined. ''; }; @@ -87,15 +84,12 @@ let type = types.nullOr types.str; default = null; example = "host canonical\nhost exec \"ping -c1 -q 192.168.17.1\""; - description = '' - Match block conditions used by this block. See - - ssh_config - 5 - - for Match block details. + description = lib.mdDoc '' + `Match` block conditions used by this block. See + {manpage}`ssh_config(5)` + for `Match` block details. This option takes precedence over - + {option}`ssh.matchBlocks.*.host` if defined. ''; }; @@ -103,13 +97,13 @@ let port = mkOption { type = types.nullOr types.port; default = null; - description = "Specifies port number to connect on remote host."; + description = lib.mdDoc "Specifies port number to connect on remote host."; }; forwardAgent = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Whether the connection to the authentication agent (if any) will be forwarded to the remote machine. ''; @@ -118,16 +112,16 @@ let forwardX11 = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Specifies whether X11 connections will be automatically redirected - over the secure channel and DISPLAY set. + over the secure channel and {env}`DISPLAY` set. ''; }; forwardX11Trusted = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Specifies whether remote X11 clients will have full access to the original X11 display. ''; @@ -136,11 +130,11 @@ let identitiesOnly = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Specifies that ssh should only use the authentication identity explicitly configured in the - ~/.ssh/config files or passed on the - ssh command-line, even if ssh-agent + {file}`~/.ssh/config` files or passed on the + ssh command-line, even if {command}`ssh-agent` offers more identities. ''; }; @@ -152,7 +146,7 @@ let if p == null then [] else if isString p then [p] else p; - description = '' + description = lib.mdDoc '' Specifies files from which the user identity is read. Identities will be tried in the given order. ''; @@ -161,26 +155,26 @@ let user = mkOption { type = types.nullOr types.str; default = null; - description = "Specifies the user to log in as."; + description = lib.mdDoc "Specifies the user to log in as."; }; hostname = mkOption { type = types.nullOr types.str; default = null; - description = "Specifies the real host name to log into."; + description = lib.mdDoc "Specifies the real host name to log into."; }; serverAliveInterval = mkOption { type = types.int; default = 0; description = - "Set timeout in seconds after which response will be requested."; + lib.mdDoc "Set timeout in seconds after which response will be requested."; }; serverAliveCountMax = mkOption { type = types.ints.positive; default = 3; - description = '' + description = lib.mdDoc '' Sets the number of server alive messages which may be sent without SSH receiving any messages back from the server. ''; @@ -189,7 +183,7 @@ let sendEnv = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Environment variables to send from the local host to the server. ''; @@ -198,7 +192,7 @@ let setEnv = mkOption { type = with types; attrsOf (oneOf [ str path int float ]); default = {}; - description = '' + description = lib.mdDoc '' Environment variables and their value to send to the server. ''; }; @@ -206,31 +200,31 @@ let compression = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' Specifies whether to use compression. Omitted from the host - block when null. + block when `null`. ''; }; checkHostIP = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Check the host IP address in the - known_hosts file. + {file}`known_hosts` file. ''; }; proxyCommand = mkOption { type = types.nullOr types.str; default = null; - description = "The command to use to connect to the server."; + description = lib.mdDoc "The command to use to connect to the server."; }; proxyJump = mkOption { type = types.nullOr types.str; default = null; - description = "The proxy host to use to connect to the server."; + description = lib.mdDoc "The proxy host to use to connect to the server."; }; certificateFile = mkOption { @@ -240,7 +234,7 @@ let if p == null then [] else if isString p then [p] else p; - description = '' + description = lib.mdDoc '' Specifies files from which the user certificate is read. ''; }; @@ -248,7 +242,7 @@ let addressFamily = mkOption { default = null; type = types.nullOr (types.enum ["any" "inet" "inet6"]); - description = '' + description = lib.mdDoc '' Specifies which address family to use when connecting. ''; }; @@ -265,12 +259,9 @@ let } ]; ''; - description = '' + description = lib.mdDoc '' Specify local port forwardings. See - - ssh_config - 5 - for LocalForward. + {manpage}`ssh_config(5)` for `LocalForward`. ''; }; @@ -286,12 +277,9 @@ let } ]; ''; - description = '' + description = lib.mdDoc '' Specify remote port forwardings. See - - ssh_config - 5 - for RemoteForward. + {manpage}`ssh_config(5)` for `RemoteForward`. ''; }; @@ -301,19 +289,16 @@ let example = literalExpression '' [ { port = 8080; } ]; ''; - description = '' + description = lib.mdDoc '' Specify dynamic port forwardings. See - - ssh_config - 5 - for DynamicForward. + {manpage}`ssh_config(5)` for `DynamicForward`. ''; }; extraOptions = mkOption { type = types.attrsOf types.str; default = {}; - description = "Extra configuration options for the host."; + description = lib.mdDoc "Extra configuration options for the host."; }; }; @@ -359,7 +344,7 @@ in meta.maintainers = [ maintainers.rycee ]; options.programs.ssh = { - enable = mkEnableOption "SSH client configuration"; + enable = mkEnableOption (lib.mdDoc "SSH client configuration"); package = mkPackageOptionMD pkgs "openssh" { nullable = true; @@ -370,7 +355,7 @@ in forwardAgent = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether the connection to the authentication agent (if any) will be forwarded to the remote machine. ''; @@ -379,13 +364,13 @@ in compression = mkOption { default = false; type = types.bool; - description = "Specifies whether to use compression."; + description = lib.mdDoc "Specifies whether to use compression."; }; serverAliveInterval = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Set default timeout in seconds after which response will be requested. ''; }; @@ -393,7 +378,7 @@ in serverAliveCountMax = mkOption { type = types.ints.positive; default = 3; - description = '' + description = lib.mdDoc '' Sets the default number of server alive messages which may be sent without SSH receiving any messages back from the server. ''; @@ -402,12 +387,9 @@ in hashKnownHosts = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Indicates that - - ssh - 1 - + {manpage}`ssh(1)` should hash host names and addresses when they are added to the known hosts file. ''; @@ -416,17 +398,17 @@ in userKnownHostsFile = mkOption { type = types.str; default = "~/.ssh/known_hosts"; - description = '' + description = lib.mdDoc '' Specifies one or more files to use for the user host key database, separated by whitespace. The default is - ~/.ssh/known_hosts. + {file}`~/.ssh/known_hosts`. ''; }; controlMaster = mkOption { default = "no"; type = types.enum ["yes" "no" "ask" "auto" "autoask"]; - description = '' + description = lib.mdDoc '' Configure sharing of multiple sessions over a single network connection. ''; }; @@ -434,7 +416,7 @@ in controlPath = mkOption { type = types.str; default = "~/.ssh/master-%r@%n:%p"; - description = '' + description = lib.mdDoc '' Specify path to the control socket used for connection sharing. ''; }; @@ -443,7 +425,7 @@ in type = types.str; default = "no"; example = "10m"; - description = '' + description = lib.mdDoc '' Whether control socket should remain open in the background. ''; }; @@ -451,7 +433,7 @@ in extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration. ''; }; @@ -459,7 +441,7 @@ in extraOptionOverrides = mkOption { type = types.attrsOf types.str; default = {}; - description = '' + description = lib.mdDoc '' Extra SSH configuration options that take precedence over any host specific configuration. ''; @@ -468,15 +450,12 @@ in includes = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' File globs of ssh config files that should be included via the - Include directive. - + `Include` directive. + See - - ssh_config - 5 - + {manpage}`ssh_config(5)` for more information. ''; }; @@ -496,16 +475,13 @@ in }; }; ''; - description = '' + description = lib.mdDoc '' Specify per-host settings. Note, if the order of rules matter then use the DAG functions to express the dependencies as shown in the example. - + See - - ssh_config - 5 - + {manpage}`ssh_config(5)` for more information. ''; }; diff --git a/modules/programs/starship.nix b/modules/programs/starship.nix index 5c90af39..52a82355 100644 --- a/modules/programs/starship.nix +++ b/modules/programs/starship.nix @@ -14,13 +14,13 @@ in { meta.maintainers = [ ]; options.programs.starship = { - enable = mkEnableOption "starship"; + enable = mkEnableOption (lib.mdDoc "starship"); package = mkOption { type = types.package; default = pkgs.starship; defaultText = literalExpression "pkgs.starship"; - description = "The package to use for the starship binary."; + description = lib.mdDoc "The package to use for the starship binary."; }; settings = mkOption { @@ -49,39 +49,40 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/starship.toml. - - See for the full list + {file}`$XDG_CONFIG_HOME/starship.toml`. + + See for the full list of options. ''; }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = true; }; - enableFishIntegration = mkEnableOption "Fish integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish integration") // { default = true; }; - enableIonIntegration = mkEnableOption "Ion integration" // { + enableIonIntegration = mkEnableOption (lib.mdDoc "Ion integration") // { default = true; }; - enableNushellIntegration = mkEnableOption "Nushell integration" // { - default = true; - }; + enableNushellIntegration = mkEnableOption (lib.mdDoc "Nushell integration") + // { + default = true; + }; enableTransience = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' The TransientPrompt feature of Starship replaces previous prompts with a custom string. This is only a valid option for the Fish shell. diff --git a/modules/programs/swaylock.nix b/modules/programs/swaylock.nix index 15b8d447..5a067232 100644 --- a/modules/programs/swaylock.nix +++ b/modules/programs/swaylock.nix @@ -16,7 +16,7 @@ in { false otherwise ''; example = true; - description = "Whether to enable swaylock."; + description = lib.mdDoc "Whether to enable swaylock."; }; package = mkPackageOptionMD pkgs "swaylock" { }; @@ -24,8 +24,8 @@ in { settings = mkOption { type = with types; attrsOf (oneOf [ bool float int str ]); default = { }; - description = '' - Default arguments to swaylock. An empty set + description = lib.mdDoc '' + Default arguments to {command}`swaylock`. An empty set disables configuration generation. ''; example = { diff --git a/modules/programs/taskwarrior.nix b/modules/programs/taskwarrior.nix index 3d3e83f8..a625159a 100644 --- a/modules/programs/taskwarrior.nix +++ b/modules/programs/taskwarrior.nix @@ -29,7 +29,7 @@ let in { options = { programs.taskwarrior = { - enable = mkEnableOption "Task Warrior"; + enable = mkEnableOption (lib.mdDoc "Task Warrior"); config = mkOption { type = types.attrsOf types.anything; @@ -49,9 +49,9 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Key-value configuration written to - $XDG_CONFIG_HOME/task/taskrc. + {file}`$XDG_CONFIG_HOME/task/taskrc`. ''; }; @@ -59,9 +59,9 @@ in { type = types.str; default = "${config.xdg.dataHome}/task"; defaultText = "$XDG_DATA_HOME/task"; - description = '' + description = lib.mdDoc '' Location where Task Warrior will store its data. - + Home Manager will attempt to create this directory. ''; }; @@ -70,7 +70,7 @@ in { type = with types; nullOr (either str path); default = null; example = "dark-blue-256"; - description = '' + description = lib.mdDoc '' Either one of the default provided theme as string, or a path to a theme configuration file. ''; @@ -79,9 +79,9 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional content written at the end of - $XDG_CONFIG_HOME/task/taskrc. + {file}`$XDG_CONFIG_HOME/task/taskrc`. ''; }; diff --git a/modules/programs/tealdeer.nix b/modules/programs/tealdeer.nix index ecb8919c..cca2a8fc 100644 --- a/modules/programs/tealdeer.nix +++ b/modules/programs/tealdeer.nix @@ -15,7 +15,7 @@ in { meta.maintainers = [ ]; options.programs.tealdeer = { - enable = mkEnableOption "Tealdeer"; + enable = mkEnableOption (lib.mdDoc "Tealdeer"); settings = mkOption { type = tomlFormat.type; @@ -32,12 +32,12 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/tealdeer/config.toml on Linux or - $HOME/Library/Application Support/tealdeer/config.toml + {file}`$XDG_CONFIG_HOME/tealdeer/config.toml` on Linux or + {file}`$HOME/Library/Application Support/tealdeer/config.toml` on Darwin. See - + for more information. ''; }; diff --git a/modules/programs/terminator.nix b/modules/programs/terminator.nix index 4a5e367b..2a996e2b 100644 --- a/modules/programs/terminator.nix +++ b/modules/programs/terminator.nix @@ -31,25 +31,23 @@ in { meta.maintainers = [ maintainers.chisui ]; options.programs.terminator = { - enable = mkEnableOption "terminator, a tiling terminal emulator"; + enable = + mkEnableOption (lib.mdDoc "terminator, a tiling terminal emulator"); package = mkOption { type = types.package; default = pkgs.terminator; example = literalExpression "pkgs.terminator"; - description = "terminator package to install."; + description = lib.mdDoc "terminator package to install."; }; config = mkOption { default = { }; - description = '' + description = lib.mdDoc '' configuration for terminator. - + For a list of all possible options refer to the - - terminator_config - 5 - + {manpage}`terminator_config(5)` man page. ''; type = types.attrsOf types.anything; diff --git a/modules/programs/termite.nix b/modules/programs/termite.nix index ccf3cabb..58f18592 100644 --- a/modules/programs/termite.nix +++ b/modules/programs/termite.nix @@ -9,12 +9,12 @@ let in { options = { programs.termite = { - enable = mkEnableOption "Termite VTE-based terminal"; + enable = mkEnableOption (lib.mdDoc "Termite VTE-based terminal"); allowBold = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Allow the output of bold characters when the bold escape sequence appears. ''; }; @@ -22,13 +22,13 @@ in { audibleBell = mkOption { default = null; type = types.nullOr types.bool; - description = "Have the terminal beep on the terminal bell."; + description = lib.mdDoc "Have the terminal beep on the terminal bell."; }; clickableUrl = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Auto-detected URLs can be clicked on to open them in your browser. Only enabled if a browser is configured or detected. ''; @@ -37,26 +37,28 @@ in { dynamicTitle = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Settings dynamic title allows the terminal and the shell to update the terminal's title. ''; }; - enableVteIntegration = mkEnableOption "Shell VTE integration" // { - default = true; - }; + enableVteIntegration = mkEnableOption (lib.mdDoc "Shell VTE integration") + // { + default = true; + }; fullscreen = mkOption { default = null; type = types.nullOr types.bool; - description = "Enables entering fullscreen mode by pressing F11."; + description = + lib.mdDoc "Enables entering fullscreen mode by pressing F11."; }; mouseAutohide = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Automatically hide the mouse pointer when you start typing. ''; }; @@ -64,13 +66,14 @@ in { scrollOnOutput = mkOption { default = null; type = types.nullOr types.bool; - description = "Scroll to the bottom when the shell generates output."; + description = + lib.mdDoc "Scroll to the bottom when the shell generates output."; }; scrollOnKeystroke = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Scroll to the bottom automatically when a key is pressed. ''; }; @@ -78,27 +81,30 @@ in { searchWrap = mkOption { default = null; type = types.nullOr types.bool; - description = "Search from top again when you hit the bottom."; + description = + lib.mdDoc "Search from top again when you hit the bottom."; }; urgentOnBell = mkOption { default = null; type = types.nullOr types.bool; - description = "Sets the window as urgent on the terminal bell."; + description = + lib.mdDoc "Sets the window as urgent on the terminal bell."; }; font = mkOption { default = null; example = "Monospace 12"; type = types.nullOr types.str; - description = "The font description for the terminal's font."; + description = lib.mdDoc "The font description for the terminal's font."; }; geometry = mkOption { default = null; example = "640x480"; type = types.nullOr types.str; - description = "The default window geometry for new terminal windows."; + description = + lib.mdDoc "The default window geometry for new terminal windows."; }; iconName = mkOption { @@ -106,14 +112,14 @@ in { example = "terminal"; type = types.nullOr types.str; description = - "The name of the icon to be used for the terminal process."; + lib.mdDoc "The name of the icon to be used for the terminal process."; }; scrollbackLines = mkOption { default = null; example = 10000; type = types.nullOr types.int; - description = + description = lib.mdDoc "Set the number of lines to limit the terminal's scrollback."; }; @@ -121,7 +127,7 @@ in { default = null; type = types.nullOr types.str; example = "${pkgs.xdg-utils}/xdg-open"; - description = '' + description = lib.mdDoc '' Set the default browser for opening links. If its not set, $BROWSER is read. If that's not set, url hints will be disabled. ''; @@ -131,7 +137,7 @@ in { default = null; example = "system"; type = types.nullOr (types.enum [ "system" "on" "off" ]); - description = '' + description = lib.mdDoc '' Specify the how the terminal's cursor should behave. Accepts system to respect the gtk global configuration, on and off to explicitly enable or disable them. @@ -142,7 +148,7 @@ in { default = null; example = "block"; type = types.nullOr (types.enum [ "block" "underline" "ibeam" ]); - description = '' + description = lib.mdDoc '' Specify how the cursor should look. Accepts block, ibeam and underline. ''; }; @@ -150,27 +156,24 @@ in { filterUnmatchedUrls = mkOption { default = null; type = types.nullOr types.bool; - description = + description = lib.mdDoc "Whether to hide url hints not matching input in url hints mode."; }; modifyOtherKeys = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Emit escape sequences for extra keys, like the modifyOtherKeys resource for - - xterm - 1 - . + {manpage}`xterm(1)`. ''; }; sizeHints = mkOption { default = null; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Enable size hints. Locks the terminal resizing to increments of the terminal's cell size. Requires a window manager that respects scroll hints. @@ -180,112 +183,112 @@ in { scrollbar = mkOption { default = null; type = types.nullOr (types.enum [ "off" "left" "right" ]); - description = "Scrollbar position."; + description = lib.mdDoc "Scrollbar position."; }; backgroundColor = mkOption { default = null; example = "rgba(63, 63, 63, 0.8)"; type = types.nullOr types.str; - description = "Background color value."; + description = lib.mdDoc "Background color value."; }; cursorColor = mkOption { default = null; example = "#dcdccc"; type = types.nullOr types.str; - description = "Cursor color value."; + description = lib.mdDoc "Cursor color value."; }; cursorForegroundColor = mkOption { default = null; example = "#dcdccc"; type = types.nullOr types.str; - description = "Cursor foreground color value."; + description = lib.mdDoc "Cursor foreground color value."; }; foregroundColor = mkOption { default = null; example = "#dcdccc"; type = types.nullOr types.str; - description = "Foreground color value."; + description = lib.mdDoc "Foreground color value."; }; foregroundBoldColor = mkOption { default = null; example = "#ffffff"; type = types.nullOr types.str; - description = "Foreground bold color value."; + description = lib.mdDoc "Foreground bold color value."; }; highlightColor = mkOption { default = null; example = "#2f2f2f"; type = types.nullOr types.str; - description = "highlight color value."; + description = lib.mdDoc "highlight color value."; }; hintsActiveBackgroundColor = mkOption { default = null; example = "#3f3f3f"; type = types.nullOr types.str; - description = "Hints active background color value."; + description = lib.mdDoc "Hints active background color value."; }; hintsActiveForegroundColor = mkOption { default = null; example = "#e68080"; type = types.nullOr types.str; - description = "Hints active foreground color value."; + description = lib.mdDoc "Hints active foreground color value."; }; hintsBackgroundColor = mkOption { default = null; example = "#3f3f3f"; type = types.nullOr types.str; - description = "Hints background color value."; + description = lib.mdDoc "Hints background color value."; }; hintsForegroundColor = mkOption { default = null; example = "#dcdccc"; type = types.nullOr types.str; - description = "Hints foreground color value."; + description = lib.mdDoc "Hints foreground color value."; }; hintsBorderColor = mkOption { default = null; example = "#3f3f3f"; type = types.nullOr types.str; - description = "Hints border color value."; + description = lib.mdDoc "Hints border color value."; }; hintsBorderWidth = mkOption { default = null; example = "0.5"; type = types.nullOr types.str; - description = "Hints border width."; + description = lib.mdDoc "Hints border width."; }; hintsFont = mkOption { default = null; example = "Monospace 12"; type = types.nullOr types.str; - description = "The font description for the hints font."; + description = lib.mdDoc "The font description for the hints font."; }; hintsPadding = mkOption { default = null; example = 2; type = types.nullOr types.int; - description = "Hints padding."; + description = lib.mdDoc "Hints padding."; }; hintsRoundness = mkOption { default = null; example = "0.2"; type = types.nullOr types.str; - description = "Hints roundness."; + description = lib.mdDoc "Hints roundness."; }; optionsExtra = mkOption { @@ -293,7 +296,7 @@ in { example = "fullscreen = true"; type = types.lines; description = - "Extra options that should be added to [options] section."; + lib.mdDoc "Extra options that should be added to [options] section."; }; colorsExtra = mkOption { @@ -304,7 +307,7 @@ in { color2 = #60b48a ''; type = types.lines; - description = + description = lib.mdDoc "Extra colors options that should be added to [colors] section."; }; @@ -312,7 +315,7 @@ in { default = ""; example = "border = #3f3f3f"; type = types.lines; - description = + description = lib.mdDoc "Extra hints options that should be added to [hints] section."; }; }; diff --git a/modules/programs/texlive.nix b/modules/programs/texlive.nix index bd17025d..420867eb 100644 --- a/modules/programs/texlive.nix +++ b/modules/programs/texlive.nix @@ -14,12 +14,12 @@ in { options = { programs.texlive = { - enable = mkEnableOption "TeX Live"; + enable = mkEnableOption (lib.mdDoc "TeX Live"); packageSet = mkOption { default = pkgs.texlive; defaultText = literalExpression "pkgs.texlive"; - description = "TeX Live package set to use."; + description = lib.mdDoc "TeX Live package set to use."; }; extraPackages = mkOption { @@ -28,12 +28,12 @@ in { example = literalExpression '' tpkgs: { inherit (tpkgs) collection-fontsrecommended algorithms; } ''; - description = "Extra packages available to TeX Live."; + description = lib.mdDoc "Extra packages available to TeX Live."; }; package = mkOption { type = types.package; - description = "Resulting customized TeX Live package."; + description = lib.mdDoc "Resulting customized TeX Live package."; readOnly = true; }; }; diff --git a/modules/programs/thunderbird.nix b/modules/programs/thunderbird.nix index b74ae8fd..d8f5d07f 100644 --- a/modules/programs/thunderbird.nix +++ b/modules/programs/thunderbird.nix @@ -124,14 +124,14 @@ in { options = { programs.thunderbird = { - enable = mkEnableOption "Thunderbird"; + enable = mkEnableOption (lib.mdDoc "Thunderbird"); package = mkOption { type = types.package; default = pkgs.thunderbird; defaultText = literalExpression "pkgs.thunderbird"; example = literalExpression "pkgs.thunderbird-91"; - description = "The Thunderbird package to use."; + description = lib.mdDoc "The Thunderbird package to use."; }; profiles = mkOption { @@ -142,14 +142,14 @@ in { type = types.str; default = name; readOnly = true; - description = "This profile's name."; + description = lib.mdDoc "This profile's name."; }; isDefault = mkOption { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether this is a default profile. There must be exactly one default profile. ''; @@ -163,9 +163,9 @@ in { "mail.spellcheck.inline" = false; } ''; - description = '' + description = lib.mdDoc '' Preferences to add to this profile's - user.js. + {file}`user.js`. ''; }; @@ -173,13 +173,14 @@ in { type = types.bool; default = false; example = true; - description = "Allow using external GPG keys with GPGME."; + description = + lib.mdDoc "Allow using external GPG keys with GPGME."; }; userChrome = mkOption { type = types.lines; default = ""; - description = "Custom Thunderbird user chrome CSS."; + description = lib.mdDoc "Custom Thunderbird user chrome CSS."; example = '' /* Hide tab bar in Thunderbird */ #tabs-toolbar { @@ -191,7 +192,7 @@ in { userContent = mkOption { type = types.lines; default = ""; - description = "Custom Thunderbird user content CSS."; + description = lib.mdDoc "Custom Thunderbird user content CSS."; example = '' /* Hide scrollbar on Thunderbird pages */ *{scrollbar-width:none !important} @@ -201,13 +202,13 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Extra preferences to add to user.js. + description = lib.mdDoc '' + Extra preferences to add to {file}`user.js`. ''; }; }; })); - description = "Attribute set of Thunderbird profiles."; + description = lib.mdDoc "Attribute set of Thunderbird profiles."; }; settings = mkOption { @@ -219,7 +220,7 @@ in { "privacy.donottrackheader.enabled" = true; } ''; - description = '' + description = lib.mdDoc '' Attribute set of Thunderbird preferences to be added to all profiles. ''; @@ -231,7 +232,7 @@ in { example = false; visible = isDarwin; readOnly = !isDarwin; - description = '' + description = lib.mdDoc '' Warn to set environment variables before using this module. Only relevant on Darwin. ''; @@ -242,8 +243,8 @@ in { type = with types; attrsOf (submodule { options.thunderbird = { - enable = - mkEnableOption "the Thunderbird mail client for this account"; + enable = mkEnableOption + (lib.mdDoc "the Thunderbird mail client for this account"); profiles = mkOption { type = with types; listOf str; @@ -251,7 +252,7 @@ in { example = literalExpression '' [ "profile1" "profile2" ] ''; - description = '' + description = lib.mdDoc '' List of Thunderbird profiles for which this account should be enabled. If this list is empty (the default), this account will be enabled for all declared profiles. @@ -267,9 +268,9 @@ in { "mail.server.server_''${id}.check_new_mail" = false; }; ''; - description = '' + description = lib.mdDoc '' Extra settings to add to this Thunderbird account configuration. - The id given as argument is an automatically + The {var}`id` given as argument is an automatically generated account identifier. ''; }; @@ -284,9 +285,9 @@ in { "mail.identity.id_''${id}.autoEncryptDrafts" = false; }; ''; - description = '' + description = lib.mdDoc '' Extra settings to add to each identity of this Thunderbird - account configuration. The id given as + account configuration. The {var}`id` given as argument is an automatically generated identifier. ''; }; diff --git a/modules/programs/timidity.nix b/modules/programs/timidity.nix index 26b9de98..61b86aaf 100644 --- a/modules/programs/timidity.nix +++ b/modules/programs/timidity.nix @@ -8,19 +8,20 @@ in { meta.maintainers = [ lib.hm.maintainers.amesgen ]; options.programs.timidity = { - enable = lib.mkEnableOption "timidity, a software MIDI renderer"; + enable = + lib.mkEnableOption (lib.mdDoc "timidity, a software MIDI renderer"); package = lib.mkOption { type = lib.types.package; default = pkgs.timidity; defaultText = lib.literalExpression "pkgs.timidity"; - description = "The timidity package to use."; + description = lib.mdDoc "The timidity package to use."; }; finalPackage = lib.mkOption { readOnly = true; type = lib.types.package; - description = "Resulting package."; + description = lib.mdDoc "Resulting package."; }; extraConfig = lib.mkOption { @@ -31,7 +32,7 @@ in { soundfont ''${pkgs.soundfont-fluid}/share/soundfonts/FluidR3_GM2-2.sf2 ''' ''; - description = "Extra configuration."; + description = lib.mdDoc "Extra configuration."; }; }; diff --git a/modules/programs/tint2.nix b/modules/programs/tint2.nix index 4579f619..dcf43bd4 100644 --- a/modules/programs/tint2.nix +++ b/modules/programs/tint2.nix @@ -10,21 +10,21 @@ in { meta.maintainers = [ hm.maintainers.CarlosLoboxyz ]; options.programs.tint2 = { - enable = - mkEnableOption "tint2, a simple, unobtrusive and light panel for Xorg"; + enable = mkEnableOption + (lib.mdDoc "tint2, a simple, unobtrusive and light panel for Xorg"); package = mkOption { type = types.package; default = pkgs.tint2; defaultText = literalExpression "pkgs.tint2"; - description = "Tint2 package to install."; + description = lib.mdDoc "Tint2 package to install."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Commands for tint2 that will be add to the tint2rc + description = lib.mdDoc '' + Commands for tint2 that will be add to the {file}`tint2rc` file. ''; }; diff --git a/modules/programs/tiny.nix b/modules/programs/tiny.nix index eba0c9c4..7c7a3297 100644 --- a/modules/programs/tiny.nix +++ b/modules/programs/tiny.nix @@ -13,13 +13,14 @@ in { options = { programs.tiny = { - enable = mkEnableOption "tiny, a TUI IRC client written in Rust"; + enable = + mkEnableOption (lib.mdDoc "tiny, a TUI IRC client written in Rust"); package = mkOption { type = types.package; default = pkgs.tiny; defaultText = literalExpression "pkgs.tiny"; - description = "The tiny package to install."; + description = lib.mdDoc "The {command}`tiny` package to install."; }; settings = mkOption { @@ -45,10 +46,10 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/tiny/config.yml. See - + {file}`$XDG_CONFIG_HOME/tiny/config.yml`. See + for the default configuration. ''; }; diff --git a/modules/programs/tmate.nix b/modules/programs/tmate.nix index 6681baf6..846fab84 100644 --- a/modules/programs/tmate.nix +++ b/modules/programs/tmate.nix @@ -11,28 +11,28 @@ in { options = { programs.tmate = { - enable = mkEnableOption "tmate"; + enable = mkEnableOption (lib.mdDoc "tmate"); package = mkOption { type = types.package; default = pkgs.tmate; defaultText = literalExpression "pkgs.tmate"; example = literalExpression "pkgs.tmate"; - description = "The tmate package to install."; + description = lib.mdDoc "The tmate package to install."; }; host = mkOption { type = with types; nullOr str; default = null; example = literalExpression "tmate.io"; - description = "Tmate server address."; + description = lib.mdDoc "Tmate server address."; }; port = mkOption { type = with types; nullOr port; default = null; example = 2222; - description = "Tmate server port."; + description = lib.mdDoc "Tmate server port."; }; dsaFingerprint = mkOption { @@ -40,7 +40,7 @@ in { default = null; example = literalExpression "SHA256:1111111111111111111111111111111111111111111"; - description = "Tmate server EdDSA key fingerprint."; + description = lib.mdDoc "Tmate server EdDSA key fingerprint."; }; rsaFingerprint = mkOption { @@ -48,15 +48,15 @@ in { default = null; example = literalExpression "SHA256:1111111111111111111111111111111111111111111"; - description = "Tmate server RSA key fingerprint."; + description = lib.mdDoc "Tmate server RSA key fingerprint."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional content written at the end of - ~/.tmate.conf. + {file}`~/.tmate.conf`. ''; }; }; diff --git a/modules/programs/tmux.nix b/modules/programs/tmux.nix index df3ed11d..fd0f0ac1 100644 --- a/modules/programs/tmux.nix +++ b/modules/programs/tmux.nix @@ -12,12 +12,13 @@ let options = { plugin = mkOption { type = types.package; - description = "Path of the configuration file to include."; + description = lib.mdDoc "Path of the configuration file to include."; }; extraConfig = mkOption { type = types.lines; - description = "Additional configuration for the associated plugin."; + description = + lib.mdDoc "Additional configuration for the associated plugin."; default = ""; }; }; @@ -134,7 +135,7 @@ in { aggressiveResize = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Resize the window to the size of the smallest session for which it is the current window. ''; @@ -144,19 +145,19 @@ in { default = 0; example = 1; type = types.ints.unsigned; - description = "Base index for windows and panes."; + description = lib.mdDoc "Base index for windows and panes."; }; clock24 = mkOption { default = false; type = types.bool; - description = "Use 24 hour clock."; + description = lib.mdDoc "Use 24 hour clock."; }; customPaneNavigationAndResize = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Override the hjkl and HJKL bindings for pane navigation and resizing in VI mode. ''; @@ -165,18 +166,18 @@ in { disableConfirmationPrompt = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Disable confirmation prompt before killing a pane or window ''; }; - enable = mkEnableOption "tmux"; + enable = mkEnableOption (lib.mdDoc "tmux"); escapeTime = mkOption { default = 500; example = 0; type = types.ints.unsigned; - description = '' + description = lib.mdDoc '' Time in milliseconds for which tmux waits after an escape is input. ''; @@ -185,9 +186,9 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional configuration to add to - tmux.conf. + {file}`tmux.conf`. ''; }; @@ -195,22 +196,23 @@ in { default = 2000; example = 5000; type = types.ints.positive; - description = "Maximum number of lines held in window history."; + description = + lib.mdDoc "Maximum number of lines held in window history."; }; keyMode = mkOption { default = defaultKeyMode; example = "vi"; type = types.enum [ "emacs" "vi" ]; - description = "VI or Emacs style shortcuts."; + description = lib.mdDoc "VI or Emacs style shortcuts."; }; - mouse = mkEnableOption "mouse support"; + mouse = mkEnableOption (lib.mdDoc "mouse support"); newSession = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Automatically spawn a session if trying to attach and none are running. ''; @@ -221,29 +223,29 @@ in { default = pkgs.tmux; defaultText = literalExpression "pkgs.tmux"; example = literalExpression "pkgs.tmux"; - description = "The tmux package to install"; + description = lib.mdDoc "The tmux package to install"; }; reverseSplit = mkOption { default = false; type = types.bool; - description = "Reverse the window split shortcuts."; + description = lib.mdDoc "Reverse the window split shortcuts."; }; resizeAmount = mkOption { default = defaultResize; example = 10; type = types.ints.positive; - description = "Number of lines/columns when resizing."; + description = lib.mdDoc "Number of lines/columns when resizing."; }; sensibleOnTop = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Run the sensible plugin at the top of the configuration. It is possible to override the sensible settings using the - option. + {option}`programs.tmux.extraConfig` option. ''; }; @@ -251,7 +253,7 @@ in { default = null; example = "C-a"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set the prefix key. Overrules the "shortcut" option when set. ''; }; @@ -260,7 +262,7 @@ in { default = defaultShortcut; example = "a"; type = types.str; - description = '' + description = lib.mdDoc '' CTRL following by this key is used as the main shortcut. ''; }; @@ -269,36 +271,36 @@ in { default = defaultTerminal; example = "screen-256color"; type = types.str; - description = "Set the $TERM variable."; + description = lib.mdDoc "Set the $TERM variable."; }; shell = mkOption { default = defaultShell; example = "\${pkgs.zsh}/bin/zsh"; type = with types; nullOr str; - description = "Set the default-shell tmux variable."; + description = lib.mdDoc "Set the default-shell tmux variable."; }; secureSocket = mkOption { default = pkgs.stdenv.isLinux; type = types.bool; - description = '' - Store tmux socket under /run, which is more - secure than /tmp, but as a downside it doesn't + description = lib.mdDoc '' + Store tmux socket under {file}`/run`, which is more + secure than {file}`/tmp`, but as a downside it doesn't survive user logout. ''; }; - tmuxp.enable = mkEnableOption "tmuxp"; + tmuxp.enable = mkEnableOption (lib.mdDoc "tmuxp"); - tmuxinator.enable = mkEnableOption "tmuxinator"; + tmuxinator.enable = mkEnableOption (lib.mdDoc "tmuxinator"); plugins = mkOption { type = with types; listOf (either package pluginModule) // { description = "list of plugin packages or submodules"; }; - description = '' + description = lib.mdDoc '' List of tmux plugins to be included at the end of your tmux configuration. The sensible plugin, however, is defaulted to run at the top of your configuration. diff --git a/modules/programs/topgrade.nix b/modules/programs/topgrade.nix index ac88643d..5572bacd 100644 --- a/modules/programs/topgrade.nix +++ b/modules/programs/topgrade.nix @@ -13,13 +13,13 @@ in { meta.maintainers = [ hm.maintainers.msfjarvis ]; options.programs.topgrade = { - enable = mkEnableOption "topgrade"; + enable = mkEnableOption (lib.mdDoc "topgrade"); package = mkOption { type = types.package; default = pkgs.topgrade; defaultText = literalExpression "pkgs.topgrade"; - description = "The package to use for the topgrade binary."; + description = lib.mdDoc "The package to use for the topgrade binary."; }; settings = mkOption { @@ -40,11 +40,11 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/topgrade.toml. - - See for the full list + {file}`$XDG_CONFIG_HOME/topgrade.toml`. + + See for the full list of options. ''; }; diff --git a/modules/programs/translate-shell.nix b/modules/programs/translate-shell.nix index 360d28f0..f4000897 100644 --- a/modules/programs/translate-shell.nix +++ b/modules/programs/translate-shell.nix @@ -25,7 +25,7 @@ in { meta.maintainers = [ ]; options.programs.translate-shell = { - enable = mkEnableOption "translate-shell"; + enable = mkEnableOption (lib.mdDoc "translate-shell"); settings = mkOption { type = with types; attrsOf (oneOf [ bool str (listOf str) ]); @@ -35,9 +35,9 @@ in { hl = "en"; tl = [ "es" "fr" ]; }; - description = '' - Options to add to $XDG_CONFIG_HOME/translate-shell/init.trans file. - See + description = lib.mdDoc '' + Options to add to {file}`$XDG_CONFIG_HOME/translate-shell/init.trans` file. + See for options. ''; }; diff --git a/modules/programs/urxvt.nix b/modules/programs/urxvt.nix index 1619ba07..3aaed951 100644 --- a/modules/programs/urxvt.nix +++ b/modules/programs/urxvt.nix @@ -8,26 +8,26 @@ let in { options.programs.urxvt = { - enable = mkEnableOption "rxvt-unicode terminal emulator"; + enable = mkEnableOption (lib.mdDoc "rxvt-unicode terminal emulator"); package = mkOption { type = types.package; default = pkgs.rxvt-unicode; defaultText = literalExpression "pkgs.rxvt-unicode"; - description = "rxvt-unicode package to install."; + description = lib.mdDoc "rxvt-unicode package to install."; }; fonts = mkOption { type = types.listOf types.str; default = [ ]; - description = "List of fonts to be used."; + description = lib.mdDoc "List of fonts to be used."; example = [ "xft:Droid Sans Mono Nerd Font:size=9" ]; }; keybindings = mkOption { type = types.attrsOf types.str; default = { }; - description = "Mapping of keybindings to actions"; + description = lib.mdDoc "Mapping of keybindings to actions"; example = literalExpression '' { "Shift-Control-C" = "eval:selection_to_clipboard"; @@ -39,7 +39,7 @@ in { iso14755 = mkOption { type = types.bool; default = true; - description = + description = lib.mdDoc "ISO14755 support for viewing and entering unicode characters."; }; @@ -50,69 +50,71 @@ in { enable = mkOption { type = types.bool; default = true; - description = "Whether to enable the scrollbar"; + description = lib.mdDoc "Whether to enable the scrollbar"; }; style = mkOption { type = types.enum [ "rxvt" "plain" "next" "xterm" ]; default = "plain"; - description = "Scrollbar style."; + description = lib.mdDoc "Scrollbar style."; }; align = mkOption { type = types.enum [ "top" "bottom" "center" ]; default = "center"; - description = "Scrollbar alignment."; + description = lib.mdDoc "Scrollbar alignment."; }; position = mkOption { type = types.enum [ "left" "right" ]; default = "right"; - description = "Scrollbar position."; + description = lib.mdDoc "Scrollbar position."; }; floating = mkOption { type = types.bool; default = true; - description = + description = lib.mdDoc "Whether to display an rxvt scrollbar without a trough."; }; }; }; default = { }; - description = "Scrollbar settings."; + description = lib.mdDoc "Scrollbar settings."; }; lines = mkOption { type = types.ints.unsigned; default = 10000; - description = "Number of lines to save in the scrollback buffer."; + description = + lib.mdDoc "Number of lines to save in the scrollback buffer."; }; keepPosition = mkOption { type = types.bool; default = true; - description = + description = lib.mdDoc "Whether to keep a scroll position when TTY receives new lines."; }; scrollOnKeystroke = mkOption { type = types.bool; default = true; - description = "Whether to scroll to bottom on keyboard input."; + description = + lib.mdDoc "Whether to scroll to bottom on keyboard input."; }; scrollOnOutput = mkOption { type = types.bool; default = false; - description = "Whether to scroll to bottom on TTY output."; + description = lib.mdDoc "Whether to scroll to bottom on TTY output."; }; }; transparent = mkOption { type = types.bool; default = false; - description = "Whether to enable pseudo-transparency."; + description = lib.mdDoc "Whether to enable pseudo-transparency."; }; shading = mkOption { @@ -125,7 +127,7 @@ in { extraConfig = mkOption { default = { }; type = types.attrsOf types.anything; - description = "Additional configuration to add."; + description = lib.mdDoc "Additional configuration to add."; example = { "shading" = 15; }; }; diff --git a/modules/programs/vdirsyncer-accounts.nix b/modules/programs/vdirsyncer-accounts.nix index 564a0948..27f9ad6b 100644 --- a/modules/programs/vdirsyncer-accounts.nix +++ b/modules/programs/vdirsyncer-accounts.nix @@ -8,12 +8,12 @@ let in { options.vdirsyncer = { - enable = mkEnableOption "synchronization using vdirsyncer"; + enable = mkEnableOption (lib.mdDoc "synchronization using vdirsyncer"); collections = mkOption { type = types.nullOr (types.listOf collection); default = null; - description = '' + description = lib.mdDoc '' The collections to synchronize between the storages. ''; }; @@ -23,10 +23,10 @@ in { (types.either (types.enum [ "remote wins" "local wins" ]) (types.listOf types.str)); default = null; - description = '' + description = lib.mdDoc '' What to do in case of a conflict between the storages. Either - remote wins or - local wins or + `remote wins` or + `local wins` or a list that contains a command to run. By default, an error message is printed. ''; @@ -35,13 +35,13 @@ in { partialSync = mkOption { type = types.nullOr (types.enum [ "revert" "error" "ignore" ]); default = null; - description = '' + description = lib.mdDoc '' What should happen if synchronization in one direction is impossible due to one storage being read-only. - Defaults to revert. - + Defaults to `revert`. + See - + for more information. ''; }; @@ -50,7 +50,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "color" "displayname" ]; - description = '' + description = lib.mdDoc '' Metadata keys that should be synchronized when vdirsyncer metasync is executed. ''; @@ -61,19 +61,19 @@ in { options = { start = mkOption { type = types.str; - description = "Start of time range to show."; + description = lib.mdDoc "Start of time range to show."; }; end = mkOption { type = types.str; - description = "End of time range to show."; + description = lib.mdDoc "End of time range to show."; }; }; }); default = null; - description = '' + description = lib.mdDoc '' A time range to synchronize. start and end can be any Python - expression that returns a datetime.datetime + expression that returns a `datetime.datetime` object. ''; example = { @@ -85,7 +85,7 @@ in { itemTypes = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = '' + description = lib.mdDoc '' Kinds of items to show. The default is to show everything. This depends on particular features of the server, the results are not validated. @@ -95,17 +95,17 @@ in { verify = mkOption { type = types.nullOr types.bool; default = null; - description = "Verify SSL certificate."; + description = lib.mdDoc "Verify SSL certificate."; }; verifyFingerprint = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Optional. SHA1 or MD5 fingerprint of the expected server certificate. - + See - + for more information. ''; }; @@ -113,15 +113,15 @@ in { auth = mkOption { type = types.nullOr (types.enum [ "basic" "digest" "guess" ]); default = null; - description = '' - Authentication settings. The default is basic. + description = lib.mdDoc '' + Authentication settings. The default is `basic`. ''; }; authCert = mkOption { type = types.nullOr (types.either types.str (types.listOf types.str)); default = null; - description = '' + description = lib.mdDoc '' Either a path to a certificate with a client certificate and the key or a list of paths to the files with them. ''; @@ -130,16 +130,16 @@ in { userAgent = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The user agent to report to the server. Defaults to - vdirsyncer. + `vdirsyncer`. ''; }; postHook = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Command to call for each item creation and modification. The command will be called with the path of the new/updated file. @@ -151,7 +151,7 @@ in { tokenFile = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' A file path where access tokens are stored. ''; }; @@ -160,12 +160,12 @@ in { type = types.nullOr (types.listOf types.str); default = null; example = [ "pass" "client_id" ]; - description = '' + description = lib.mdDoc '' A command that prints the OAuth credentials to standard output. - + See - + for more information. ''; }; @@ -174,12 +174,12 @@ in { type = types.nullOr (types.listOf types.str); default = null; example = [ "pass" "client_secret" ]; - description = '' + description = lib.mdDoc '' A command that prints the OAuth credentials to standard output. - + See - + for more information. ''; }; diff --git a/modules/programs/vdirsyncer.nix b/modules/programs/vdirsyncer.nix index 91671c18..89adba96 100644 --- a/modules/programs/vdirsyncer.nix +++ b/modules/programs/vdirsyncer.nix @@ -167,13 +167,13 @@ let in { options = { programs.vdirsyncer = { - enable = mkEnableOption "vdirsyncer"; + enable = mkEnableOption (lib.mdDoc "vdirsyncer"); package = mkOption { type = types.package; default = pkgs.vdirsyncer; defaultText = "pkgs.vdirsyncer"; - description = '' + description = lib.mdDoc '' vdirsyncer package to use. ''; }; diff --git a/modules/programs/vim-vint.nix b/modules/programs/vim-vint.nix index c9fdf256..bafcc69b 100644 --- a/modules/programs/vim-vint.nix +++ b/modules/programs/vim-vint.nix @@ -13,15 +13,15 @@ in { options = { programs.vim-vint = { - enable = mkEnableOption "the Vint linter for Vimscript"; + enable = mkEnableOption (lib.mdDoc "the Vint linter for Vimscript"); package = mkPackageOptionMD pkgs "vim-vint" { }; settings = mkOption { type = yamlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/.vintrc.yaml + {file}`$XDG_CONFIG_HOME/.vintrc.yaml` ''; }; }; diff --git a/modules/programs/vim.nix b/modules/programs/vim.nix index 8a7618dd..56d8aa81 100644 --- a/modules/programs/vim.nix +++ b/modules/programs/vim.nix @@ -63,17 +63,15 @@ let in { options = { programs.vim = { - enable = mkEnableOption "Vim"; + enable = mkEnableOption (lib.mdDoc "Vim"); plugins = mkOption { type = with types; listOf (either str package); default = defaultPlugins; example = literalExpression "[ pkgs.vimPlugins.YankRing ]"; - description = '' + description = lib.mdDoc '' List of vim plugins to install. To get a list of supported plugins run: - nix-env -f '<nixpkgs>' -qaP -A vimPlugins. - - + {command}`nix-env -f '' -qaP -A vimPlugins`. Note: String values are deprecated, please use actual packages. ''; @@ -112,18 +110,18 @@ in { set nocompatible set nobackup ''; - description = "Custom .vimrc lines"; + description = lib.mdDoc "Custom .vimrc lines"; }; package = mkOption { type = types.package; - description = "Resulting customized vim package"; + description = lib.mdDoc "Resulting customized vim package"; readOnly = true; }; packageConfigurable = mkOption { type = types.package; - description = "Vim package to customize"; + description = lib.mdDoc "Vim package to customize"; default = pkgs.vim-full or pkgs.vim_configurable; defaultText = literalExpression "pkgs.vim-full"; example = literalExpression "pkgs.vim"; @@ -132,9 +130,9 @@ in { defaultEditor = mkOption { type = types.bool; default = false; - description = '' - Whether to configure vim as the default - editor using the EDITOR environment variable. + description = lib.mdDoc '' + Whether to configure {command}`vim` as the default + editor using the {env}`EDITOR` environment variable. ''; }; }; diff --git a/modules/programs/vscode.nix b/modules/programs/vscode.nix index 779565d2..b2797546 100644 --- a/modules/programs/vscode.nix +++ b/modules/programs/vscode.nix @@ -60,14 +60,14 @@ in { options = { programs.vscode = { - enable = mkEnableOption "Visual Studio Code"; + enable = mkEnableOption (lib.mdDoc "Visual Studio Code"); package = mkOption { type = types.package; default = pkgs.vscode; defaultText = literalExpression "pkgs.vscode"; example = literalExpression "pkgs.vscodium"; - description = '' + description = lib.mdDoc '' Version of Visual Studio Code to install. ''; }; @@ -75,7 +75,7 @@ in { enableUpdateCheck = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable update checks/notifications. ''; }; @@ -83,7 +83,7 @@ in { enableExtensionUpdateCheck = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable update notifications for extensions. ''; }; @@ -97,9 +97,9 @@ in { "[nix]"."editor.tabSize" = 2; } ''; - description = '' + description = lib.mdDoc '' Configuration written to Visual Studio Code's - settings.json. + {file}`settings.json`. ''; }; @@ -118,9 +118,9 @@ in { ]; } ''; - description = '' + description = lib.mdDoc '' Configuration written to Visual Studio Code's - tasks.json. + {file}`tasks.json`. ''; }; @@ -130,20 +130,20 @@ in { key = mkOption { type = types.str; example = "ctrl+c"; - description = "The key or key-combination to bind."; + description = lib.mdDoc "The key or key-combination to bind."; }; command = mkOption { type = types.str; example = "editor.action.clipboardCopyAction"; - description = "The VS Code command to execute."; + description = lib.mdDoc "The VS Code command to execute."; }; when = mkOption { type = types.nullOr (types.str); default = null; example = "textInputFocus"; - description = "Optional context filter."; + description = lib.mdDoc "Optional context filter."; }; # https://code.visualstudio.com/docs/getstarted/keybindings#_command-arguments @@ -151,7 +151,7 @@ in { type = types.nullOr (jsonFormat.type); default = null; example = { direction = "up"; }; - description = "Optional arguments for a command."; + description = lib.mdDoc "Optional arguments for a command."; }; }; }); @@ -165,9 +165,9 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' Keybindings written to Visual Studio Code's - keybindings.json. + {file}`keybindings.json`. ''; }; @@ -175,7 +175,7 @@ in { type = types.listOf types.package; default = [ ]; example = literalExpression "[ pkgs.vscode-extensions.bbenoist.nix ]"; - description = '' + description = lib.mdDoc '' The extensions Visual Studio Code should be started with. ''; }; @@ -184,7 +184,7 @@ in { type = types.bool; default = true; example = false; - description = '' + description = lib.mdDoc '' Whether extensions can be installed or updated manually or by Visual Studio Code. ''; @@ -202,7 +202,8 @@ in { }; }; }; - description = "Defines user snippets for different languages."; + description = + lib.mdDoc "Defines user snippets for different languages."; }; globalSnippets = mkOption { @@ -215,7 +216,7 @@ in { description = "Insert a FIXME remark"; }; }; - description = "Defines global user snippets."; + description = lib.mdDoc "Defines global user snippets."; }; }; }; diff --git a/modules/programs/vscode/haskell.nix b/modules/programs/vscode/haskell.nix index 4867d0a7..a2f2147a 100644 --- a/modules/programs/vscode/haskell.nix +++ b/modules/programs/vscode/haskell.nix @@ -23,12 +23,14 @@ let in { options.programs.vscode.haskell = { - enable = mkEnableOption "Haskell integration for Visual Studio Code"; + enable = + mkEnableOption (lib.mdDoc "Haskell integration for Visual Studio Code"); hie.enable = mkOption { type = types.bool; default = true; - description = "Whether to enable Haskell IDE engine integration."; + description = + lib.mdDoc "Whether to enable Haskell IDE engine integration."; }; hie.executablePath = mkOption { diff --git a/modules/programs/watson.nix b/modules/programs/watson.nix index 54cfbc13..3fa9b146 100644 --- a/modules/programs/watson.nix +++ b/modules/programs/watson.nix @@ -17,36 +17,40 @@ in { meta.maintainers = [ maintainers.polykernel ]; options.programs.watson = { - enable = mkEnableOption "watson, a wonderful CLI to track your time"; + enable = + mkEnableOption (lib.mdDoc "watson, a wonderful CLI to track your time"); package = mkOption { type = types.package; default = pkgs.watson; defaultText = literalExpression "pkgs.watson"; - description = "Package providing the watson."; + description = lib.mdDoc "Package providing the {command}`watson`."; }; - enableBashIntegration = mkEnableOption "watson's bash integration" // { - default = true; - }; + enableBashIntegration = + mkEnableOption (lib.mdDoc "watson's bash integration") // { + default = true; + }; - enableZshIntegration = mkEnableOption "watson's zsh integration" // { - default = true; - }; + enableZshIntegration = mkEnableOption (lib.mdDoc "watson's zsh integration") + // { + default = true; + }; - enableFishIntegration = mkEnableOption "watson's fish integration" // { - default = true; - }; + enableFishIntegration = + mkEnableOption (lib.mdDoc "watson's fish integration") // { + default = true; + }; settings = mkOption { type = iniFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/watson/config on Linux or - $HOME/Library/Application Support/watson/config on Darwin. - - See + {file}`$XDG_CONFIG_HOME/watson/config` on Linux or + {file}`$HOME/Library/Application Support/watson/config` on Darwin. + + See for an example configuration. ''; example = literalExpression '' diff --git a/modules/programs/waybar.nix b/modules/programs/waybar.nix index 7a5f11f1..3303ed7f 100644 --- a/modules/programs/waybar.nix +++ b/modules/programs/waybar.nix @@ -15,7 +15,7 @@ let type = types.nullOr types.int; default = null; example = 10; - description = "Margin value without unit."; + description = lib.mdDoc "Margin value without unit."; }; waybarBarConfig = with types; @@ -26,9 +26,9 @@ let layer = mkOption { type = nullOr (enum [ "top" "bottom" ]); default = null; - description = '' - Decide if the bar is displayed in front ("top") - of the windows or behind ("bottom"). + description = lib.mdDoc '' + Decide if the bar is displayed in front (`"top"`) + of the windows or behind (`"bottom"`). ''; example = "top"; }; @@ -39,7 +39,7 @@ let example = literalExpression '' [ "DP-1" "!DP-2" "!DP-3" ] ''; - description = '' + description = lib.mdDoc '' Specifies on which screen this bar will be displayed. Exclamation mark(!) can be used to exclude specific output. ''; @@ -49,14 +49,14 @@ let type = nullOr (enum [ "top" "bottom" "left" "right" ]); default = null; example = "right"; - description = "Bar position relative to the output."; + description = lib.mdDoc "Bar position relative to the output."; }; height = mkOption { type = nullOr ints.unsigned; default = null; example = 5; - description = + description = lib.mdDoc "Height to be used by the bar if possible. Leave blank for a dynamic value."; }; @@ -64,14 +64,14 @@ let type = nullOr ints.unsigned; default = null; example = 5; - description = + description = lib.mdDoc "Width to be used by the bar if possible. Leave blank for a dynamic value."; }; modules-left = mkOption { type = listOf str; default = [ ]; - description = "Modules that will be displayed on the left."; + description = lib.mdDoc "Modules that will be displayed on the left."; example = literalExpression '' [ "sway/workspaces" "sway/mode" "wlr/taskbar" ] ''; @@ -80,7 +80,8 @@ let modules-center = mkOption { type = listOf str; default = [ ]; - description = "Modules that will be displayed in the center."; + description = + lib.mdDoc "Modules that will be displayed in the center."; example = literalExpression '' [ "sway/window" ] ''; @@ -89,7 +90,8 @@ let modules-right = mkOption { type = listOf str; default = [ ]; - description = "Modules that will be displayed on the right."; + description = + lib.mdDoc "Modules that will be displayed on the right."; example = literalExpression '' [ "mpd" "custom/mymodule#with-css-id" "temperature" ] ''; @@ -99,7 +101,7 @@ let type = jsonFormat.type; visible = false; default = null; - description = "Modules configuration."; + description = lib.mdDoc "Modules configuration."; example = literalExpression '' { "sway/window" = { @@ -115,7 +117,8 @@ let margin = mkOption { type = nullOr str; default = null; - description = "Margins value using the CSS format without units."; + description = + lib.mdDoc "Margins value using the CSS format without units."; example = "20 5"; }; @@ -127,7 +130,7 @@ let name = mkOption { type = nullOr str; default = null; - description = + description = lib.mdDoc "Optional name added as a CSS class, for styling multiple waybars."; example = "waybar-1"; }; @@ -136,7 +139,7 @@ let type = nullOr bool; default = null; example = false; - description = + description = lib.mdDoc "Option to disable the use of gtk-layer-shell for popups."; }; }; @@ -145,23 +148,22 @@ in { meta.maintainers = with lib.maintainers; [ berbiche ]; options.programs.waybar = with lib.types; { - enable = mkEnableOption "Waybar"; + enable = mkEnableOption (lib.mdDoc "Waybar"); package = mkOption { type = package; default = pkgs.waybar; defaultText = literalExpression "pkgs.waybar"; - description = '' - Waybar package to use. Set to null to use the default package. + description = lib.mdDoc '' + Waybar package to use. Set to `null` to use the default package. ''; }; settings = mkOption { type = either (listOf waybarBarConfig) (attrsOf waybarBarConfig); default = [ ]; - description = '' - Configuration for Waybar, see + description = lib.mdDoc '' + Configuration for Waybar, see for supported values. ''; example = literalExpression '' @@ -195,18 +197,17 @@ in { ''; }; - systemd.enable = mkEnableOption "Waybar systemd integration"; + systemd.enable = mkEnableOption (lib.mdDoc "Waybar systemd integration"); systemd.target = mkOption { type = str; default = "graphical-session.target"; example = "sway-session.target"; - description = '' + description = lib.mdDoc '' The systemd target that will automatically start the Waybar service. - - - When setting this value to "sway-session.target", - make sure to also enable , + + When setting this value to `"sway-session.target"`, + make sure to also enable {option}`wayland.windowManager.sway.systemd.enable`, otherwise the service may never be started. ''; }; @@ -214,14 +215,12 @@ in { style = mkOption { type = nullOr (either path lines); default = null; - description = '' + description = lib.mdDoc '' CSS style of the bar. - - - See + + See for the documentation. - - + If the value is set to a path literal, then the path will be used as the css file. ''; example = '' diff --git a/modules/programs/wezterm.nix b/modules/programs/wezterm.nix index e7da436f..93861cd0 100644 --- a/modules/programs/wezterm.nix +++ b/modules/programs/wezterm.nix @@ -15,13 +15,13 @@ in { meta.maintainers = [ hm.maintainers.blmhemu ]; options.programs.wezterm = { - enable = mkEnableOption "wezterm"; + enable = mkEnableOption (lib.mdDoc "wezterm"); package = mkOption { type = types.package; default = pkgs.wezterm; defaultText = literalExpression "pkgs.wezterm"; - description = "The Wezterm package to install."; + description = lib.mdDoc "The Wezterm package to install."; }; extraConfig = mkOption { @@ -44,10 +44,10 @@ in { } } ''; - description = '' + description = lib.mdDoc '' Extra configuration written to - $XDG_CONFIG_HOME/wezterm/wezterm.lua. See - + {file}`$XDG_CONFIG_HOME/wezterm/wezterm.lua`. See + how to configure. ''; }; @@ -74,22 +74,24 @@ in { selection_fg = "#E9E9E9"; }; ''; - description = '' + description = lib.mdDoc '' Attribute set of additional color schemes to be written to - $XDG_CONFIG_HOME/wezterm/colors, where each key is + {file}`$XDG_CONFIG_HOME/wezterm/colors`, where each key is taken as the name of the corresponding color scheme. See - + for more details of the TOML color scheme format. ''; }; - enableBashIntegration = mkEnableOption "WezTerm's Bash integration" // { - default = true; - }; + enableBashIntegration = + mkEnableOption (lib.mdDoc "WezTerm's Bash integration") // { + default = true; + }; - enableZshIntegration = mkEnableOption "WezTerm's Zsh integration" // { - default = true; - }; + enableZshIntegration = + mkEnableOption (lib.mdDoc "WezTerm's Zsh integration") // { + default = true; + }; }; config = mkIf cfg.enable { diff --git a/modules/programs/wlogout.nix b/modules/programs/wlogout.nix index 8ff7566d..28b443f5 100644 --- a/modules/programs/wlogout.nix +++ b/modules/programs/wlogout.nix @@ -20,49 +20,49 @@ let type = str; default = ""; example = "shutdown"; - description = "CSS label of button."; + description = lib.mdDoc "CSS label of button."; }; action = mkOption { type = either path str; default = ""; example = "systemctl poweroff"; - description = "Command to execute when clicked."; + description = lib.mdDoc "Command to execute when clicked."; }; text = mkOption { type = str; default = ""; example = "Shutdown"; - description = "Text displayed on button."; + description = lib.mdDoc "Text displayed on button."; }; keybind = mkOption { type = str; default = ""; example = "s"; - description = "Keyboard character to trigger this action."; + description = lib.mdDoc "Keyboard character to trigger this action."; }; height = mkOption { type = nullOr (numbers.between 0 1); default = null; example = 0.5; - description = "Relative height of tile."; + description = lib.mdDoc "Relative height of tile."; }; width = mkOption { type = nullOr (numbers.between 0 1); default = null; example = 0.5; - description = "Relative width of tile."; + description = lib.mdDoc "Relative width of tile."; }; circular = mkOption { type = nullOr bool; default = null; example = true; - description = "Make button circular."; + description = lib.mdDoc "Make button circular."; }; }; }; @@ -70,16 +70,15 @@ in { meta.maintainers = [ lib.maintainers.Scrumplex ]; options.programs.wlogout = with lib.types; { - enable = mkEnableOption "wlogout"; + enable = mkEnableOption (lib.mdDoc "wlogout"); package = mkPackageOptionMD pkgs "wlogout" { }; layout = mkOption { type = listOf wlogoutLayoutConfig; default = [ ]; - description = '' - Layout configuration for wlogout, see + description = lib.mdDoc '' + Layout configuration for wlogout, see for supported values. ''; example = literalExpression '' @@ -97,14 +96,12 @@ in { style = mkOption { type = nullOr (either path str); default = null; - description = '' + description = lib.mdDoc '' CSS style of the bar. - - - See + + See for the documentation. - - + If the value is set to a path literal, then the path will be used as the css file. ''; example = '' diff --git a/modules/programs/wofi.nix b/modules/programs/wofi.nix index 474f03ba..e4969e40 100644 --- a/modules/programs/wofi.nix +++ b/modules/programs/wofi.nix @@ -14,20 +14,17 @@ in { meta.maintainers = [ maintainers.christoph-heiss ]; options.programs.wofi = { - enable = mkEnableOption - "wofi: a launcher/menu program for wlroots based wayland compositors such as sway"; + enable = mkEnableOption (lib.mdDoc + "wofi: a launcher/menu program for wlroots based wayland compositors such as sway"); package = mkPackageOptionMD pkgs "wofi" { }; settings = mkOption { default = { }; type = types.attrs; - description = '' + description = lib.mdDoc '' Configuration options for wofi. See - - wofi - 5 - . + {manpage}`wofi(5)`. ''; example = literalExpression '' { @@ -41,12 +38,9 @@ in { style = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' CSS style for wofi to use as a stylesheet. See - - wofi - 7 - . + {manpage}`wofi(7)`. ''; example = '' * { diff --git a/modules/programs/xmobar.nix b/modules/programs/xmobar.nix index a29bea84..6c712c67 100644 --- a/modules/programs/xmobar.nix +++ b/modules/programs/xmobar.nix @@ -5,14 +5,14 @@ with lib; let cfg = config.programs.xmobar; in { options.programs.xmobar = { - enable = mkEnableOption "Xmobar, a minimalistic status bar"; + enable = mkEnableOption (lib.mdDoc "Xmobar, a minimalistic status bar"); package = mkOption { default = pkgs.haskellPackages.xmobar; defaultText = literalExpression "pkgs.haskellPackages.xmobar"; type = types.package; - description = '' - Package providing the xmobar binary. + description = lib.mdDoc '' + Package providing the {command}`xmobar` binary. ''; }; @@ -40,11 +40,11 @@ in { } ''; type = types.lines; - description = '' + description = lib.mdDoc '' Extra configuration lines to add to - $XDG_CONFIG_HOME/xmobar/.xmobarrc. + {file}`$XDG_CONFIG_HOME/xmobar/.xmobarrc`. See - + for options. ''; }; diff --git a/modules/programs/yt-dlp.nix b/modules/programs/yt-dlp.nix index 8febb059..f54dd88d 100644 --- a/modules/programs/yt-dlp.nix +++ b/modules/programs/yt-dlp.nix @@ -16,13 +16,13 @@ in { meta.maintainers = [ ]; options.programs.yt-dlp = { - enable = mkEnableOption "yt-dlp"; + enable = mkEnableOption (lib.mdDoc "yt-dlp"); package = mkOption { type = types.package; default = pkgs.yt-dlp; defaultText = literalExpression "pkgs.yt-dlp"; - description = "Package providing the yt-dlp tool."; + description = lib.mdDoc "Package providing the {command}`yt-dlp` tool."; }; settings = mkOption { @@ -37,14 +37,14 @@ in { downloader-args = "aria2c:'-c -x8 -s8 -k1M'"; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/yt-dlp/config. - + {file}`$XDG_CONFIG_HOME/yt-dlp/config`. + Options must be specified in their "long form", for - example, update = true; instead of U = true;. - Short options can be specified in the extraConfig option. - See + example, `update = true;` instead of `U = true;`. + Short options can be specified in the `extraConfig` option. + See for explanation about possible values. ''; }; @@ -56,9 +56,9 @@ in { --update -F ''; - description = '' + description = lib.mdDoc '' Extra configuration to add to - $XDG_CONFIG_HOME/yt-dlp/config. + {file}`$XDG_CONFIG_HOME/yt-dlp/config`. ''; }; }; diff --git a/modules/programs/z-lua.nix b/modules/programs/z-lua.nix index 37a8479e..1105f2f6 100644 --- a/modules/programs/z-lua.nix +++ b/modules/programs/z-lua.nix @@ -18,13 +18,13 @@ in { meta.maintainers = [ ]; options.programs.z-lua = { - enable = mkEnableOption "z.lua"; + enable = mkEnableOption (lib.mdDoc "z.lua"); options = mkOption { type = types.listOf types.str; default = [ ]; example = [ "enhanced" "once" "fzf" ]; - description = '' + description = lib.mdDoc '' List of options to pass to z.lua. ''; }; @@ -32,7 +32,7 @@ in { enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -40,7 +40,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -48,7 +48,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; @@ -56,7 +56,7 @@ in { enableAliases = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable recommended z.lua aliases. ''; }; diff --git a/modules/programs/zathura.nix b/modules/programs/zathura.nix index b043fa23..9b916caf 100644 --- a/modules/programs/zathura.nix +++ b/modules/programs/zathura.nix @@ -18,27 +18,24 @@ in { meta.maintainers = [ maintainers.rprospero ]; options.programs.zathura = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Zathura, a highly customizable and functional document viewer - focused on keyboard interaction''; + focused on keyboard interaction''); package = mkOption { type = types.package; default = pkgs.zathura; defaultText = "pkgs.zathura"; - description = "The Zathura package to use"; + description = lib.mdDoc "The Zathura package to use"; }; options = mkOption { default = { }; type = with types; attrsOf (either str (either bool int)); - description = '' - Add command options to zathura and make + description = lib.mdDoc '' + Add {option}`:set` command options to zathura and make them permanent. See - - zathurarc - 5 - + {manpage}`zathurarc(5)` for the full list of options. ''; example = { @@ -50,17 +47,14 @@ in { mappings = mkOption { default = { }; type = with types; attrsOf str; - description = '' - Add mappings to zathura and make + description = lib.mdDoc '' + Add {option}`:map` mappings to zathura and make them permanent. See - - zathurarc - 5 - + {manpage}`zathurarc(5)` for the full list of possible mappings. You can create a mode-specific mapping by specifying the mode before the key: - "[normal] <C-b>" = "scroll left"; + `"[normal] " = "scroll left";` ''; example = { D = "toggle_page_mode"; @@ -72,9 +66,9 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Additional commands for zathura that will be added to the - zathurarc file. + {file}`zathurarc` file. ''; }; }; diff --git a/modules/programs/zellij.nix b/modules/programs/zellij.nix index e1973025..e956db82 100644 --- a/modules/programs/zellij.nix +++ b/modules/programs/zellij.nix @@ -11,13 +11,13 @@ in { meta.maintainers = [ hm.maintainers.mainrs ]; options.programs.zellij = { - enable = mkEnableOption "zellij"; + enable = mkEnableOption (lib.mdDoc "zellij"); package = mkOption { type = types.package; default = pkgs.zellij; defaultText = literalExpression "pkgs.zellij"; - description = '' + description = lib.mdDoc '' The zellij package to install. ''; }; @@ -31,24 +31,24 @@ in { themes.custom.fg = "#ffffff"; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/zellij/config.yaml. - - See for the full + {file}`$XDG_CONFIG_HOME/zellij/config.yaml`. + + See for the full list of options. ''; }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = false; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = false; }; - enableFishIntegration = mkEnableOption "Fish integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish integration") // { default = false; }; }; diff --git a/modules/programs/zoxide.nix b/modules/programs/zoxide.nix index 11ae353c..3035fca8 100644 --- a/modules/programs/zoxide.nix +++ b/modules/programs/zoxide.nix @@ -12,13 +12,13 @@ in { meta.maintainers = [ ]; options.programs.zoxide = { - enable = mkEnableOption "zoxide"; + enable = mkEnableOption (lib.mdDoc "zoxide"); package = mkOption { type = types.package; default = pkgs.zoxide; defaultText = literalExpression "pkgs.zoxide"; - description = '' + description = lib.mdDoc '' Zoxide package to install. ''; }; @@ -27,7 +27,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--no-aliases" ]; - description = '' + description = lib.mdDoc '' List of options to pass to zoxide. ''; }; @@ -35,7 +35,7 @@ in { enableBashIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Bash integration. ''; }; @@ -43,7 +43,7 @@ in { enableZshIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Zsh integration. ''; }; @@ -51,7 +51,7 @@ in { enableFishIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Fish integration. ''; }; @@ -59,7 +59,7 @@ in { enableNushellIntegration = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Whether to enable Nushell integration. ''; }; diff --git a/modules/programs/zplug.nix b/modules/programs/zplug.nix index 94e3173a..2fb7b0ce 100644 --- a/modules/programs/zplug.nix +++ b/modules/programs/zplug.nix @@ -10,13 +10,13 @@ let options = { name = mkOption { type = types.str; - description = "The name of the plugin."; + description = lib.mdDoc "The name of the plugin."; }; tags = mkOption { type = types.listOf types.str; default = [ ]; - description = "The plugin tags."; + description = lib.mdDoc "The plugin tags."; }; }; @@ -24,12 +24,12 @@ let in { options.programs.zsh.zplug = { - enable = mkEnableOption "zplug - a zsh plugin manager"; + enable = mkEnableOption (lib.mdDoc "zplug - a zsh plugin manager"); plugins = mkOption { default = [ ]; type = types.listOf pluginModule; - description = "List of zplug plugins."; + description = lib.mdDoc "List of zplug plugins."; }; zplugHome = mkOption { @@ -37,7 +37,7 @@ in { default = "${config.home.homeDirectory}/.zplug"; defaultText = "~/.zplug"; apply = toString; - description = "Path to zplug home directory."; + description = lib.mdDoc "Path to zplug home directory."; }; }; diff --git a/modules/programs/zsh.nix b/modules/programs/zsh.nix index d2d9a7a5..6281d166 100644 --- a/modules/programs/zsh.nix +++ b/modules/programs/zsh.nix @@ -37,14 +37,14 @@ let size = mkOption { type = types.int; default = 10000; - description = "Number of history lines to keep."; + description = lib.mdDoc "Number of history lines to keep."; }; save = mkOption { type = types.int; defaultText = 10000; default = config.size; - description = "Number of history lines to save."; + description = lib.mdDoc "Number of history lines to save."; }; path = mkOption { @@ -57,14 +57,14 @@ let "$ZDOTDIR/.zsh_history" otherwise ''; example = literalExpression ''"''${config.xdg.dataHome}/zsh/zsh_history"''; - description = "History file location"; + description = lib.mdDoc "History file location"; }; ignorePatterns = mkOption { type = types.listOf types.str; default = []; example = literalExpression ''[ "rm *" "pkill *" ]''; - description = '' + description = lib.mdDoc '' Do not enter command lines into the history list if they match any one of the given shell patterns. ''; @@ -73,7 +73,7 @@ let ignoreDups = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Do not enter command lines into the history list if they are duplicates of the previous event. ''; @@ -82,7 +82,7 @@ let ignoreSpace = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Do not enter command lines into the history list if the first character is a space. ''; @@ -91,19 +91,19 @@ let expireDuplicatesFirst = mkOption { type = types.bool; default = false; - description = "Expire duplicates first."; + description = lib.mdDoc "Expire duplicates first."; }; extended = mkOption { type = types.bool; default = false; - description = "Save timestamp into the history file."; + description = lib.mdDoc "Save timestamp into the history file."; }; share = mkOption { type = types.bool; default = true; - description = "Share command history between zsh sessions."; + description = lib.mdDoc "Share command history between zsh sessions."; }; }; }); @@ -112,26 +112,26 @@ let options = { src = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Path to the plugin folder. - Will be added to fpath and PATH. + Will be added to {env}`fpath` and {env}`PATH`. ''; }; name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The name of the plugin. - Don't forget to add + Don't forget to add {option}`file` if the script name does not follow convention. ''; }; file = mkOption { type = types.str; - description = "The plugin script to source."; + description = lib.mdDoc "The plugin script to source."; }; }; @@ -140,7 +140,7 @@ let ohMyZshModule = types.submodule { options = { - enable = mkEnableOption "oh-my-zsh"; + enable = mkEnableOption (lib.mdDoc "oh-my-zsh"); package = mkPackageOptionMD pkgs "oh-my-zsh" { }; @@ -148,7 +148,7 @@ let default = []; example = [ "git" "sudo" ]; type = types.listOf types.str; - description = '' + description = lib.mdDoc '' List of oh-my-zsh plugins ''; }; @@ -157,9 +157,9 @@ let default = ""; type = types.str; example = "$HOME/my_customizations"; - description = '' + description = lib.mdDoc '' Path to a custom oh-my-zsh package to override config of - oh-my-zsh. See + oh-my-zsh. See for more information. ''; }; @@ -168,7 +168,7 @@ let default = ""; example = "robbyrussell"; type = types.str; - description = '' + description = lib.mdDoc '' Name of the theme to be used by oh-my-zsh. ''; }; @@ -179,7 +179,7 @@ let zstyle :omz:plugins:ssh-agent identities id_rsa id_rsa2 id_github ''; type = types.lines; - description = '' + description = lib.mdDoc '' Extra settings for plugins. ''; }; @@ -188,21 +188,21 @@ let historySubstringSearchModule = types.submodule { options = { - enable = mkEnableOption "history substring search"; + enable = mkEnableOption (lib.mdDoc "history substring search"); searchUpKey = mkOption { type = with types; either (listOf str) str ; default = [ "^[[A" ]; - description = '' + description = lib.mdDoc '' The key codes to be used when searching up. - The default of ^[[A corresponds to the UP key. + The default of `^[[A` corresponds to the UP key. ''; }; searchDownKey = mkOption { type = with types; either (listOf str) str ; default = [ "^[[B" ]; - description = '' + description = lib.mdDoc '' The key codes to be used when searching down. - The default of ^[[B corresponds to the DOWN key. + The default of `^[[B` corresponds to the DOWN key. ''; }; }; @@ -210,16 +210,16 @@ let syntaxHighlightingModule = types.submodule { options = { - enable = mkEnableOption "zsh syntax highlighting"; + enable = mkEnableOption (lib.mdDoc "zsh syntax highlighting"); package = mkPackageOptionMD pkgs "zsh-syntax-highlighting" { }; styles = mkOption { type = types.attrsOf types.str; default = {}; - description = '' + description = lib.mdDoc '' Custom styles for syntax highlighting. - See each highlighter's options: + See each highlighter's options: ''; }; }; @@ -234,13 +234,13 @@ in options = { programs.zsh = { - enable = mkEnableOption "Z shell (Zsh)"; + enable = mkEnableOption (lib.mdDoc "Z shell (Zsh)"); package = mkPackageOptionMD pkgs "zsh" { }; autocd = mkOption { default = null; - description = '' + description = lib.mdDoc '' Automatically enter into a directory if typed directly into shell. ''; type = types.nullOr types.bool; @@ -257,7 +257,7 @@ in dotDir = mkOption { default = null; example = ".config/zsh"; - description = '' + description = lib.mdDoc '' Directory where the zsh configuration and more should be located, relative to the users home directory. The default is the home directory. @@ -273,7 +273,7 @@ in ".." = "cd .."; } ''; - description = '' + description = lib.mdDoc '' An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. ''; @@ -288,8 +288,8 @@ in G = "| grep"; } ''; - description = '' - Similar to , + description = lib.mdDoc '' + Similar to [](#opt-programs.zsh.shellAliases), but are substituted anywhere on a line. ''; type = types.attrsOf types.str; @@ -304,7 +304,7 @@ in dl = "$HOME/Downloads"; } ''; - description = '' + description = lib.mdDoc '' An attribute set that adds to named directory hash table. ''; type = types.attrsOf types.str; @@ -312,11 +312,11 @@ in enableCompletion = mkOption { default = true; - description = '' + description = lib.mdDoc '' Enable zsh completion. Don't forget to add - + ```nix environment.pathsToLink = [ "/share/zsh" ]; - + ``` to your system configuration to get completion for system packages (e.g. systemd). ''; type = types.bool; @@ -324,87 +324,87 @@ in completionInit = mkOption { default = "autoload -U compinit && compinit"; - description = "Initialization commands to run when completion is enabled."; + description = lib.mdDoc "Initialization commands to run when completion is enabled."; type = types.lines; }; enableAutosuggestions = mkOption { default = false; - description = "Enable zsh autosuggestions"; + description = lib.mdDoc "Enable zsh autosuggestions"; }; syntaxHighlighting = mkOption { type = syntaxHighlightingModule; default = {}; - description = "Options related to zsh-syntax-highlighting."; + description = lib.mdDoc "Options related to zsh-syntax-highlighting."; }; historySubstringSearch = mkOption { type = historySubstringSearchModule; default = {}; - description = "Options related to zsh-history-substring-search."; + description = lib.mdDoc "Options related to zsh-history-substring-search."; }; history = mkOption { type = historyModule; default = {}; - description = "Options related to commands history configuration."; + description = lib.mdDoc "Options related to commands history configuration."; }; defaultKeymap = mkOption { type = types.nullOr (types.enum (attrNames bindkeyCommands)); default = null; example = "emacs"; - description = "The default base keymap to use."; + description = lib.mdDoc "The default base keymap to use."; }; sessionVariables = mkOption { default = {}; type = types.attrs; example = { MAILCHECK = 30; }; - description = "Environment variables that will be set for zsh session."; + description = lib.mdDoc "Environment variables that will be set for zsh session."; }; initExtraBeforeCompInit = mkOption { default = ""; type = types.lines; - description = "Extra commands that should be added to .zshrc before compinit."; + description = lib.mdDoc "Extra commands that should be added to {file}`.zshrc` before compinit."; }; initExtra = mkOption { default = ""; type = types.lines; - description = "Extra commands that should be added to .zshrc."; + description = lib.mdDoc "Extra commands that should be added to {file}`.zshrc`."; }; initExtraFirst = mkOption { default = ""; type = types.lines; - description = "Commands that should be added to top of .zshrc."; + description = lib.mdDoc "Commands that should be added to top of {file}`.zshrc`."; }; envExtra = mkOption { default = ""; type = types.lines; - description = "Extra commands that should be added to .zshenv."; + description = lib.mdDoc "Extra commands that should be added to {file}`.zshenv`."; }; profileExtra = mkOption { default = ""; type = types.lines; - description = "Extra commands that should be added to .zprofile."; + description = lib.mdDoc "Extra commands that should be added to {file}`.zprofile`."; }; loginExtra = mkOption { default = ""; type = types.lines; - description = "Extra commands that should be added to .zlogin."; + description = lib.mdDoc "Extra commands that should be added to {file}`.zlogin`."; }; logoutExtra = mkOption { default = ""; type = types.lines; - description = "Extra commands that should be added to .zlogout."; + description = lib.mdDoc "Extra commands that should be added to {file}`.zlogout`."; }; plugins = mkOption { @@ -434,21 +434,21 @@ in } ] ''; - description = "Plugins to source in .zshrc."; + description = lib.mdDoc "Plugins to source in {file}`.zshrc`."; }; oh-my-zsh = mkOption { type = ohMyZshModule; default = {}; - description = "Options to configure oh-my-zsh."; + description = lib.mdDoc "Options to configure oh-my-zsh."; }; localVariables = mkOption { type = types.attrs; default = {}; example = { POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=["dir" "vcs"]; }; - description = '' - Extra local variables defined at the top of .zshrc. + description = lib.mdDoc '' + Extra local variables defined at the top of {file}`.zshrc`. ''; }; }; diff --git a/modules/programs/zsh/prezto.nix b/modules/programs/zsh/prezto.nix index 5673c28f..fd33f0d6 100644 --- a/modules/programs/zsh/prezto.nix +++ b/modules/programs/zsh/prezto.nix @@ -12,14 +12,14 @@ let preztoModule = types.submodule { options = { - enable = mkEnableOption "prezto"; + enable = mkEnableOption (lib.mdDoc "prezto"); caseSensitive = mkOption { type = types.nullOr types.bool; default = null; example = true; description = - "Set case-sensitivity for completion, history lookup, etc."; + lib.mdDoc "Set case-sensitivity for completion, history lookup, etc."; }; color = mkOption { @@ -35,14 +35,15 @@ let type = types.listOf types.path; default = [ ]; example = [ "$HOME/.zprezto-contrib" ]; - description = "Add additional directories to load prezto modules from."; + description = + lib.mdDoc "Add additional directories to load prezto modules from."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = '' - Additional configuration to add to .zpreztorc. + description = lib.mdDoc '' + Additional configuration to add to {file}`.zpreztorc`. ''; }; @@ -77,7 +78,7 @@ let "completion" "prompt" ]; - description = + description = lib.mdDoc "Set the Prezto modules to load (browse modules). The order matters."; }; @@ -85,7 +86,7 @@ let type = types.nullOr types.str; default = null; example = "fg=blue"; - description = "Set the query found color."; + description = lib.mdDoc "Set the query found color."; }; completions.ignoredHosts = mkOption { @@ -121,7 +122,7 @@ let type = types.nullOr types.bool; default = null; example = true; - description = "Allow the Zsh prompt context to be shown."; + description = lib.mdDoc "Allow the Zsh prompt context to be shown."; }; }; @@ -139,7 +140,7 @@ let type = types.nullOr types.str; default = null; example = "g"; - description = "Set the command prefix on non-GNU systems."; + description = lib.mdDoc "Set the command prefix on non-GNU systems."; }; historySubstring = { @@ -147,20 +148,20 @@ let type = types.nullOr types.str; default = null; example = "fg=blue"; - description = "Set the query found color."; + description = lib.mdDoc "Set the query found color."; }; notFoundColor = mkOption { type = types.nullOr types.str; default = null; example = "fg=red"; - description = "Set the query not found color."; + description = lib.mdDoc "Set the query not found color."; }; globbingFlags = mkOption { type = types.nullOr types.str; default = null; - description = "Set the search globbing flags."; + description = lib.mdDoc "Set the search globbing flags."; }; }; @@ -202,7 +203,7 @@ let type = types.nullOr types.bool; default = null; example = true; - description = '' + description = lib.mdDoc '' Set the prompt to display the return code along with an indicator for non-zero return codes. This is not supported by all prompts. ''; @@ -214,14 +215,15 @@ let type = types.nullOr types.bool; default = null; example = true; - description = "Auto switch to Python virtualenv on directory change."; + description = + lib.mdDoc "Auto switch to Python virtualenv on directory change."; }; virtualenvInitialize = mkOption { type = types.nullOr types.bool; default = null; example = true; - description = + description = lib.mdDoc "Automatically initialize virtualenvwrapper if pre-requisites are met."; }; }; @@ -230,7 +232,8 @@ let type = types.nullOr types.bool; default = null; example = true; - description = "Auto switch the Ruby version on directory change."; + description = + lib.mdDoc "Auto switch the Ruby version on directory change."; }; screen = { @@ -238,7 +241,7 @@ let type = types.nullOr types.bool; default = null; example = true; - description = + description = lib.mdDoc "Auto start a session when Zsh is launched in a local terminal."; }; @@ -246,7 +249,7 @@ let type = types.nullOr types.bool; default = null; example = true; - description = + description = lib.mdDoc "Auto start a session when Zsh is launched in a SSH connection."; }; }; @@ -255,7 +258,8 @@ let type = types.listOf types.str; default = [ ]; example = [ "id_rsa" "id_rsa2" "id_github" ]; - description = "Set the SSH identities to load into the agent."; + description = + lib.mdDoc "Set the SSH identities to load into the agent."; }; syntaxHighlighting = { @@ -263,7 +267,7 @@ let type = types.listOf types.str; default = [ ]; example = [ "main" "brackets" "pattern" "line" "cursor" "root" ]; - description = '' + description = lib.mdDoc '' Set syntax highlighters. By default, only the main highlighter is enabled. ''; @@ -277,14 +281,14 @@ let command = "bg=blue"; function = "bg=blue"; }; - description = "Set syntax highlighting styles."; + description = lib.mdDoc "Set syntax highlighting styles."; }; pattern = mkOption { type = types.attrsOf types.str; default = { }; example = { "rm*-rf*" = "fg=white,bold,bg=red"; }; - description = "Set syntax pattern styles."; + description = lib.mdDoc "Set syntax pattern styles."; }; }; @@ -293,28 +297,28 @@ let type = types.nullOr types.bool; default = null; example = true; - description = "Auto set the tab and window titles."; + description = lib.mdDoc "Auto set the tab and window titles."; }; windowTitleFormat = mkOption { type = types.nullOr types.str; default = null; example = "%n@%m: %s"; - description = "Set the window title format."; + description = lib.mdDoc "Set the window title format."; }; tabTitleFormat = mkOption { type = types.nullOr types.str; default = null; example = "%m: %s"; - description = "Set the tab title format."; + description = lib.mdDoc "Set the tab title format."; }; multiplexerTitleFormat = mkOption { type = types.nullOr types.str; default = null; example = "%s"; - description = "Set the multiplexer title format."; + description = lib.mdDoc "Set the multiplexer title format."; }; }; @@ -323,7 +327,7 @@ let type = types.nullOr types.bool; default = null; example = true; - description = + description = lib.mdDoc "Auto start a session when Zsh is launched in a local terminal."; }; @@ -331,7 +335,7 @@ let type = types.nullOr types.bool; default = null; example = true; - description = + description = lib.mdDoc "Auto start a session when Zsh is launched in a SSH connection."; }; @@ -339,14 +343,14 @@ let type = types.nullOr types.bool; default = null; example = true; - description = "Integrate with iTerm2."; + description = lib.mdDoc "Integrate with iTerm2."; }; defaultSessionName = mkOption { type = types.nullOr types.str; default = null; example = "YOUR DEFAULT SESSION NAME"; - description = "Set the default session name."; + description = lib.mdDoc "Set the default session name."; }; }; @@ -371,7 +375,7 @@ in { prezto = mkOption { type = preztoModule; default = { }; - description = "Options to configure prezto."; + description = lib.mdDoc "Options to configure prezto."; }; }; }; diff --git a/modules/services/autorandr.nix b/modules/services/autorandr.nix index 9ce668d7..1f0fa8ca 100644 --- a/modules/services/autorandr.nix +++ b/modules/services/autorandr.nix @@ -22,7 +22,7 @@ in { default = false; type = types.bool; description = - "Treat outputs as connected even if their lids are closed."; + lib.mdDoc "Treat outputs as connected even if their lids are closed."; }; }; }; diff --git a/modules/services/avizo.nix b/modules/services/avizo.nix index 70a0e0b6..87f4c312 100644 --- a/modules/services/avizo.nix +++ b/modules/services/avizo.nix @@ -9,7 +9,7 @@ in { meta.maintainers = [ hm.maintainers.pltanton ]; options.services.avizo = { - enable = mkEnableOption "avizo, a simple notification daemon"; + enable = mkEnableOption (lib.mdDoc "avizo, a simple notification daemon"); settings = mkOption { type = (pkgs.formats.ini { }).type; @@ -25,7 +25,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' The settings that will be written to the avizo configuration file. ''; }; @@ -39,7 +39,7 @@ in { patchPhase = "cp ''${./images}/*.png data/images/"; }) ''; - description = "The avizo package to use."; + description = lib.mdDoc "The `avizo` package to use."; }; }; diff --git a/modules/services/barrier.nix b/modules/services/barrier.nix index b619cb28..16ab0b4c 100644 --- a/modules/services/barrier.nix +++ b/modules/services/barrier.nix @@ -16,38 +16,38 @@ in { client = { - enable = mkEnableOption "Barrier Client daemon"; + enable = mkEnableOption (lib.mdDoc "Barrier Client daemon"); name = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Screen name of client. Defaults to hostname. ''; }; server = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Server to connect to formatted as - <host>[:<port>]. - Port defaults to 24800. + `[:]`. + Port defaults to `24800`. ''; }; - enableCrypto = mkEnableOption "crypto (SSL) plugin" // { + enableCrypto = mkEnableOption (lib.mdDoc "crypto (SSL) plugin") // { default = true; }; - enableDragDrop = mkEnableOption "file drag & drop"; + enableDragDrop = mkEnableOption (lib.mdDoc "file drag & drop"); extraFlags = mkOption { type = types.listOf types.str; default = [ "-f" ]; defaultText = literalExpression ''[ "-f" ]''; - description = '' - Additional flags to pass to barrierc. - See barrierc --help. + description = lib.mdDoc '' + Additional flags to pass to {command}`barrierc`. + See {command}`barrierc --help`. ''; }; diff --git a/modules/services/batsignal.nix b/modules/services/batsignal.nix index 131eeb2f..d0eb854b 100644 --- a/modules/services/batsignal.nix +++ b/modules/services/batsignal.nix @@ -9,14 +9,14 @@ in { options = { services.batsignal = { - enable = lib.mkEnableOption "Batsignal Battery Daemon"; + enable = lib.mkEnableOption (lib.mdDoc "Batsignal Battery Daemon"); package = lib.mkPackageOptionMD pkgs "batsignal" { }; extraArgs = lib.mkOption { type = with lib.types; listOf str; default = [ ]; - description = '' + description = lib.mdDoc '' Extra arguments to be passed to the batsignal executable. ''; }; diff --git a/modules/services/betterlockscreen.nix b/modules/services/betterlockscreen.nix index b4b28b5f..c3be8f05 100644 --- a/modules/services/betterlockscreen.nix +++ b/modules/services/betterlockscreen.nix @@ -9,27 +9,29 @@ in { options = { services.betterlockscreen = { - enable = mkEnableOption "betterlockscreen, a screen-locker module"; + enable = + mkEnableOption (lib.mdDoc "betterlockscreen, a screen-locker module"); package = mkOption { type = types.package; default = pkgs.betterlockscreen; defaultText = literalExpression "pkgs.betterlockscreen"; - description = "Package providing betterlockscreen."; + description = + lib.mdDoc "Package providing {command}`betterlockscreen`."; }; arguments = mkOption { type = types.listOf types.str; default = [ ]; - description = - "List of arguments appended to ./betterlockscreen --lock [args]"; + description = lib.mdDoc + "List of arguments appended to `./betterlockscreen --lock [args]`"; }; inactiveInterval = mkOption { type = types.int; default = 10; - description = '' - Value used for . + description = lib.mdDoc '' + Value used for {option}`services.screen-locker.inactiveInterval`. ''; }; diff --git a/modules/services/borgmatic.nix b/modules/services/borgmatic.nix index 62c834a8..7f723695 100644 --- a/modules/services/borgmatic.nix +++ b/modules/services/borgmatic.nix @@ -10,20 +10,17 @@ in { options = { services.borgmatic = { - enable = mkEnableOption "Borgmatic service"; + enable = mkEnableOption (lib.mdDoc "Borgmatic service"); frequency = mkOption { type = types.str; default = "hourly"; - description = '' + description = lib.mdDoc '' How often to run borgmatic when - services.borgmatic.enable = true. + `services.borgmatic.enable = true`. This value is passed to the systemd timer configuration as the onCalendar option. See - - systemd.time - 7 - + {manpage}`systemd.time(7)` for more information about the format. ''; }; diff --git a/modules/services/cachix-agent.nix b/modules/services/cachix-agent.nix index 2f1e42ca..4cf81009 100644 --- a/modules/services/cachix-agent.nix +++ b/modules/services/cachix-agent.nix @@ -10,20 +10,20 @@ in { meta.maintainers = [ maintainers.rycee ]; options.services.cachix-agent = { - enable = mkEnableOption '' - Cachix Deploy Agent: ''; + enable = mkEnableOption + (lib.mdDoc "Cachix Deploy Agent: "); name = mkOption { type = types.str; - description = "The unique agent name."; + description = lib.mdDoc "The unique agent name."; }; - verbose = mkEnableOption "verbose output"; + verbose = mkEnableOption (lib.mdDoc "verbose output"); profile = mkOption { type = types.str; default = "home-manager"; - description = '' + description = lib.mdDoc '' The Nix profile name. ''; }; @@ -31,7 +31,7 @@ in { host = mkOption { type = types.nullOr types.str; default = null; - description = "Cachix URI to use."; + description = lib.mdDoc "Cachix URI to use."; }; package = mkPackageOptionMD pkgs "cachix" { }; @@ -41,9 +41,9 @@ in { default = "${config.xdg.configHome}/cachix-agent.token"; defaultText = literalExpression ''"''${config.xdg.configHome}/cachix-agent.token"''; - description = '' + description = lib.mdDoc '' Required file that needs to contain - CACHIX_AGENT_TOKEN=.... + `CACHIX_AGENT_TOKEN=...`. ''; }; }; diff --git a/modules/services/caffeine.nix b/modules/services/caffeine.nix index 28ebc7f1..3b8f014b 100644 --- a/modules/services/caffeine.nix +++ b/modules/services/caffeine.nix @@ -10,7 +10,9 @@ in { meta.maintainers = [ maintainers.uvnikita ]; options = { - services.caffeine = { enable = mkEnableOption "Caffeine service"; }; + services.caffeine = { + enable = mkEnableOption (lib.mdDoc "Caffeine service"); + }; }; config = mkIf cfg.enable { diff --git a/modules/services/cbatticon.nix b/modules/services/cbatticon.nix index 1216878c..64e488e3 100644 --- a/modules/services/cbatticon.nix +++ b/modules/services/cbatticon.nix @@ -31,7 +31,7 @@ in { options = { services.cbatticon = { - enable = mkEnableOption "cbatticon"; + enable = mkEnableOption (lib.mdDoc "cbatticon"); commandCriticalLevel = mkOption { type = types.nullOr types.lines; @@ -39,7 +39,7 @@ in { example = '' notify-send "battery critical!" ''; - description = '' + description = lib.mdDoc '' Command to execute when the critical battery level is reached. ''; }; @@ -47,7 +47,7 @@ in { commandLeftClick = mkOption { type = types.nullOr types.lines; default = null; - description = '' + description = lib.mdDoc '' Command to execute when left clicking on the tray icon. ''; }; @@ -57,14 +57,14 @@ in { types.nullOr (types.enum [ "standard" "notification" "symbolic" ]); default = null; example = "symbolic"; - description = "Icon type to display in the system tray."; + description = lib.mdDoc "Icon type to display in the system tray."; }; lowLevelPercent = mkOption { type = types.nullOr (types.ints.between 0 100); default = null; example = 20; - description = '' + description = lib.mdDoc '' Low level percentage of the battery in percent (without the percent symbol). ''; @@ -74,7 +74,7 @@ in { type = types.nullOr (types.ints.between 0 100); default = null; example = 5; - description = '' + description = lib.mdDoc '' Critical level percentage of the battery in percent (without the percent symbol). ''; @@ -84,7 +84,7 @@ in { type = types.nullOr types.ints.positive; default = null; example = 5; - description = '' + description = lib.mdDoc '' Number of seconds between updates of the battery information. ''; }; @@ -92,7 +92,7 @@ in { hideNotification = mkOption { type = types.nullOr types.bool; default = null; - description = "Hide the notification popups."; + description = lib.mdDoc "Hide the notification popups."; }; }; }; diff --git a/modules/services/clipman.nix b/modules/services/clipman.nix index 9186c8b0..1abbb520 100644 --- a/modules/services/clipman.nix +++ b/modules/services/clipman.nix @@ -5,7 +5,8 @@ in { meta.maintainers = [ maintainers.jwygoda ]; options.services.clipman = { - enable = mkEnableOption "clipman, a simple clipboard manager for Wayland"; + enable = mkEnableOption + (lib.mdDoc "clipman, a simple clipboard manager for Wayland"); package = mkPackageOptionMD pkgs "clipman" { }; @@ -13,12 +14,11 @@ in { type = types.str; default = "graphical-session.target"; example = "sway-session.target"; - description = '' + description = lib.mdDoc '' The systemd target that will automatically start the clipman service. - - - When setting this value to "sway-session.target", - make sure to also enable , + + When setting this value to `"sway-session.target"`, + make sure to also enable {option}`wayland.windowManager.sway.systemd.enable`, otherwise the service may never be started. ''; }; diff --git a/modules/services/clipmenu.nix b/modules/services/clipmenu.nix index 4bb8916f..2e4abd92 100644 --- a/modules/services/clipmenu.nix +++ b/modules/services/clipmenu.nix @@ -10,21 +10,22 @@ in { meta.maintainers = [ maintainers.DamienCassou ]; options.services.clipmenu = { - enable = mkEnableOption "clipmenu, the clipboard management daemon"; + enable = + mkEnableOption (lib.mdDoc "clipmenu, the clipboard management daemon"); package = mkOption { type = types.package; default = pkgs.clipmenu; defaultText = "pkgs.clipmenu"; - description = "clipmenu derivation to use."; + description = lib.mdDoc "clipmenu derivation to use."; }; launcher = mkOption { type = types.nullOr types.str; default = null; example = "rofi"; - description = '' - Launcher command, if not set, dmenu + description = lib.mdDoc '' + Launcher command, if not set, {command}`dmenu` will be used by default. ''; }; diff --git a/modules/services/comodoro.nix b/modules/services/comodoro.nix index 4458807b..c5c3e065 100644 --- a/modules/services/comodoro.nix +++ b/modules/services/comodoro.nix @@ -15,7 +15,7 @@ in { meta.maintainers = with lib.hm.maintainers; [ soywod ]; options.services.comodoro = { - enable = lib.mkEnableOption "Comodoro server"; + enable = lib.mkEnableOption (lib.mdDoc "Comodoro server"); package = lib.mkPackageOptionMD pkgs "comodoro" { }; @@ -27,21 +27,21 @@ in { "PASSWORD_STORE_DIR" = "~/.password-store"; } ''; - description = '' + description = lib.mdDoc '' Extra environment variables to be exported in the service. ''; }; preset = lib.mkOption { type = lib.types.nonEmptyStr; - description = '' + description = lib.mdDoc '' Use configuration from the given preset as defined in the configuration file. ''; }; protocols = lib.mkOption { type = with lib.types; nonEmptyListOf nonEmptyStr; - description = '' + description = lib.mdDoc '' Define protocols the server should use to accept requests. ''; }; diff --git a/modules/services/copyq.nix b/modules/services/copyq.nix index 745ca0df..23765b52 100644 --- a/modules/services/copyq.nix +++ b/modules/services/copyq.nix @@ -8,8 +8,8 @@ in { meta.maintainers = [ lib.maintainers.DamienCassou ]; options.services.copyq = { - enable = - lib.mkEnableOption "CopyQ, a clipboard manager with advanced features"; + enable = lib.mkEnableOption + (lib.mdDoc "CopyQ, a clipboard manager with advanced features"); package = lib.mkPackageOptionMD pkgs "copyq" { }; @@ -17,12 +17,11 @@ in { type = lib.types.str; default = "graphical-session.target"; example = "sway-session.target"; - description = '' + description = lib.mdDoc '' The systemd target that will automatically start the CopyQ service. - - - When setting this value to "sway-session.target", - make sure to also enable , + + When setting this value to `"sway-session.target"`, + make sure to also enable {option}`wayland.windowManager.sway.systemd.enable`, otherwise the service may never be started. ''; }; diff --git a/modules/services/devilspie2.nix b/modules/services/devilspie2.nix index fa77153e..68f1a4f2 100644 --- a/modules/services/devilspie2.nix +++ b/modules/services/devilspie2.nix @@ -7,14 +7,14 @@ in { options = { services.devilspie2 = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Devilspie2, a window matching utility, allowing the user to - perform scripted actions on windows as they are created''; + perform scripted actions on windows as they are created''); config = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Content of file placed in the devilspie2 config directory. ''; example = '' diff --git a/modules/services/dropbox.nix b/modules/services/dropbox.nix index 941f4d82..fd8eb2e7 100644 --- a/modules/services/dropbox.nix +++ b/modules/services/dropbox.nix @@ -14,7 +14,7 @@ in { options = { services.dropbox = { - enable = mkEnableOption "Dropbox daemon"; + enable = mkEnableOption (lib.mdDoc "Dropbox daemon"); path = mkOption { type = types.path; @@ -22,7 +22,7 @@ in { defaultText = literalExpression ''"''${config.home.homeDirectory}/Dropbox"''; apply = toString; # Prevent copies to Nix store. - description = "Where to put the Dropbox directory."; + description = lib.mdDoc "Where to put the Dropbox directory."; }; }; }; diff --git a/modules/services/dunst.nix b/modules/services/dunst.nix index 8606e248..c678d2f4 100644 --- a/modules/services/dunst.nix +++ b/modules/services/dunst.nix @@ -26,20 +26,20 @@ let package = mkOption { type = types.package; example = literalExpression "pkgs.gnome.adwaita-icon-theme"; - description = "Package providing the theme."; + description = lib.mdDoc "Package providing the theme."; }; name = mkOption { type = types.str; example = "Adwaita"; - description = "The name of the theme within the package."; + description = lib.mdDoc "The name of the theme within the package."; }; size = mkOption { type = types.str; default = "32x32"; example = "16x16"; - description = "The desired icon size."; + description = lib.mdDoc "The desired icon size."; }; }; }; @@ -55,24 +55,24 @@ in { options = { services.dunst = { - enable = mkEnableOption "the dunst notification daemon"; + enable = mkEnableOption (lib.mdDoc "the dunst notification daemon"); package = mkOption { type = types.package; default = pkgs.dunst; defaultText = literalExpression "pkgs.dunst"; - description = "Package providing dunst."; + description = lib.mdDoc "Package providing {command}`dunst`."; }; configFile = mkOption { type = with types; either str path; default = "${config.xdg.configHome}/dunst/dunstrc"; defaultText = "$XDG_CONFIG_HOME/dunst/dunstrc"; - description = '' + description = lib.mdDoc '' Path to the configuration file read by dunst. - + Note that the configuration generated by Home Manager will be - written to $XDG_CONFIG_HOME/dunst/dunstrc + written to {file}`$XDG_CONFIG_HOME/dunst/dunstrc` regardless. This allows using a mutable configuration file generated from the immutable one, useful in scenarios where live reloading is desired. @@ -82,14 +82,14 @@ in { iconTheme = mkOption { type = themeType; default = hicolorTheme; - description = "Set the icon theme."; + description = lib.mdDoc "Set the icon theme."; }; waylandDisplay = mkOption { type = types.str; default = ""; - description = - "Set the service's WAYLAND_DISPLAY environment variable."; + description = lib.mdDoc + "Set the service's {env}`WAYLAND_DISPLAY` environment variable."; }; settings = mkOption { @@ -98,13 +98,13 @@ in { options = { global.icon_path = mkOption { type = types.separatedString ":"; - description = "Paths where dunst will look for icons."; + description = lib.mdDoc "Paths where dunst will look for icons."; }; }; }; default = { }; - description = - "Configuration written to $XDG_CONFIG_HOME/dunst/dunstrc."; + description = lib.mdDoc + "Configuration written to {file}`$XDG_CONFIG_HOME/dunst/dunstrc`."; example = literalExpression '' { global = { diff --git a/modules/services/dwm-status.nix b/modules/services/dwm-status.nix index c3295faa..78ebc891 100644 --- a/modules/services/dwm-status.nix +++ b/modules/services/dwm-status.nix @@ -16,19 +16,19 @@ let in { options = { services.dwm-status = { - enable = mkEnableOption "dwm-status user service"; + enable = mkEnableOption (lib.mdDoc "dwm-status user service"); package = mkOption { type = types.package; default = pkgs.dwm-status; defaultText = literalExpression "pkgs.dwm-status"; example = "pkgs.dwm-status.override { enableAlsaUtils = false; }"; - description = "Which dwm-status package to use."; + description = lib.mdDoc "Which dwm-status package to use."; }; order = mkOption { type = types.listOf (types.enum features); - description = "List of enabled features in order."; + description = lib.mdDoc "List of enabled features in order."; }; extraConfig = mkOption { @@ -47,7 +47,7 @@ in { }; } ''; - description = "Extra config of dwm-status."; + description = lib.mdDoc "Extra config of dwm-status."; }; }; }; diff --git a/modules/services/easyeffects.nix b/modules/services/easyeffects.nix index 9dd01b94..f14330e1 100644 --- a/modules/services/easyeffects.nix +++ b/modules/services/easyeffects.nix @@ -12,25 +12,25 @@ in { meta.maintainers = [ maintainers.fufexan ]; options.services.easyeffects = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Easyeffects daemon. Note, it is necessary to add - + ```nix programs.dconf.enable = true; - - to your system configuration for the daemon to work correctly''; + ``` + to your system configuration for the daemon to work correctly''); package = mkOption { type = types.package; default = pkgs.easyeffects; defaultText = literalExpression "pkgs.easyeffects"; - description = "The easyeffects package to use."; + description = lib.mdDoc "The `easyeffects` package to use."; }; preset = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' Which preset to use when starting easyeffects. Will likely need to launch easyeffects to initially create preset. ''; diff --git a/modules/services/emacs.nix b/modules/services/emacs.nix index 2d5a24b9..e8a888da 100644 --- a/modules/services/emacs.nix +++ b/modules/services/emacs.nix @@ -42,7 +42,7 @@ in { meta.maintainers = [ maintainers.tadfisher ]; options.services.emacs = { - enable = mkEnableOption "the Emacs daemon"; + enable = mkEnableOption (lib.mdDoc "the Emacs daemon"); package = mkOption { type = types.package; @@ -51,25 +51,26 @@ in { if config.programs.emacs.enable then config.programs.emacs.finalPackage else pkgs.emacs ''; - description = "The Emacs package to use."; + description = lib.mdDoc "The Emacs package to use."; }; extraOptions = mkOption { type = with types; listOf str; default = [ ]; example = [ "-f" "exwm-enable" ]; - description = '' - Extra command-line arguments to pass to emacs. + description = lib.mdDoc '' + Extra command-line arguments to pass to {command}`emacs`. ''; }; client = { - enable = mkEnableOption "generation of Emacs client desktop file"; + enable = + mkEnableOption (lib.mdDoc "generation of Emacs client desktop file"); arguments = mkOption { type = with types; listOf str; default = [ "-c" ]; - description = '' - Command-line arguments to pass to emacsclient. + description = lib.mdDoc '' + Command-line arguments to pass to {command}`emacsclient`. ''; }; }; @@ -78,7 +79,8 @@ in { # socket path, though allowing for such is not easy to do as systemd socket # units don't perform variable expansion for 'ListenStream'. socketActivation = { - enable = mkEnableOption "systemd socket activation for the Emacs service"; + enable = mkEnableOption + (lib.mdDoc "systemd socket activation for the Emacs service"); }; startWithUserSession = mkOption { @@ -87,12 +89,12 @@ in { defaultText = literalExpression "!config.services.emacs.socketActivation.enable"; example = "graphical"; - description = '' + description = lib.mdDoc '' Whether to launch Emacs service with the systemd user session. If it is - true, Emacs service is started by - default.target. If it is - "graphical", Emacs service is started by - graphical-session.target. + `true`, Emacs service is started by + `default.target`. If it is + `"graphical"`, Emacs service is started by + `graphical-session.target`. ''; }; @@ -100,9 +102,9 @@ in { type = types.bool; default = false; example = !default; - description = '' - Whether to configure emacsclient as the default - editor using the EDITOR environment variable. + description = lib.mdDoc '' + Whether to configure {command}`emacsclient` as the default + editor using the {env}`EDITOR` environment variable. ''; }; }; diff --git a/modules/services/espanso.nix b/modules/services/espanso.nix index ec8ace5e..9e44f9be 100644 --- a/modules/services/espanso.nix +++ b/modules/services/espanso.nix @@ -22,11 +22,12 @@ in { ]; options = { services.espanso = { - enable = mkEnableOption "Espanso: cross platform text expander in Rust"; + enable = mkEnableOption + (lib.mdDoc "Espanso: cross platform text expander in Rust"); package = mkOption { type = types.package; - description = "Which espanso package to use"; + description = lib.mdDoc "Which espanso package to use"; default = pkgs.espanso; defaultText = literalExpression "pkgs.espanso"; }; @@ -45,9 +46,9 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' The Espanso configuration to use. See - + for a description of available options. ''; }; @@ -89,9 +90,9 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' The Espanso matches to use. See - + for a description of available options. ''; }; diff --git a/modules/services/etesync-dav.nix b/modules/services/etesync-dav.nix index 5fd58d09..5119deb6 100644 --- a/modules/services/etesync-dav.nix +++ b/modules/services/etesync-dav.nix @@ -14,19 +14,19 @@ in { meta.maintainers = [ maintainers.valodim ]; options.services.etesync-dav = { - enable = mkEnableOption "etesync-dav"; + enable = mkEnableOption (lib.mdDoc "etesync-dav"); package = mkOption { type = types.package; default = pkgs.etesync-dav; defaultText = "pkgs.etesync-dav"; - description = "The etesync-dav derivation to use."; + description = lib.mdDoc "The etesync-dav derivation to use."; }; serverUrl = mkOption { type = types.str; default = "https://api.etesync.com/"; - description = "The URL to the etesync server."; + description = lib.mdDoc "The URL to the etesync server."; }; settings = mkOption { @@ -38,7 +38,7 @@ in { ETESYNC_LISTEN_PORT = 37358; } ''; - description = '' + description = lib.mdDoc '' Settings for etesync-dav, passed as environment variables. ''; }; diff --git a/modules/services/flameshot.nix b/modules/services/flameshot.nix index 2de0d547..1b07e05f 100644 --- a/modules/services/flameshot.nix +++ b/modules/services/flameshot.nix @@ -14,13 +14,13 @@ in { meta.maintainers = [ maintainers.hamhut1066 ]; options.services.flameshot = { - enable = mkEnableOption "Flameshot"; + enable = mkEnableOption (lib.mdDoc "Flameshot"); package = mkOption { type = types.package; default = pkgs.flameshot; defaultText = literalExpression "pkgs.flameshot"; - description = "Package providing flameshot."; + description = lib.mdDoc "Package providing {command}`flameshot`."; }; settings = mkOption { @@ -32,9 +32,9 @@ in { showStartupLaunchMessage = false; }; }; - description = '' + description = lib.mdDoc '' Configuration to use for Flameshot. See - + for available options. ''; }; diff --git a/modules/services/fluidsynth.nix b/modules/services/fluidsynth.nix index bf1b76a0..cb266608 100644 --- a/modules/services/fluidsynth.nix +++ b/modules/services/fluidsynth.nix @@ -11,12 +11,12 @@ in { options = { services.fluidsynth = { - enable = mkEnableOption "fluidsynth midi synthesizer"; + enable = mkEnableOption (lib.mdDoc "fluidsynth midi synthesizer"); soundFont = mkOption { type = types.path; default = "${pkgs.soundfont-fluid}/share/soundfonts/FluidR3_GM2-2.sf2"; - description = '' + description = lib.mdDoc '' The soundfont file to use, in SoundFont 2 format. ''; }; @@ -25,7 +25,7 @@ in { type = types.enum [ "jack" "pipewire-pulse" "pulseaudio" ]; default = "pulseaudio"; example = "pipewire-pulse"; - description = '' + description = lib.mdDoc '' The systemd sound service to depend on. ''; }; @@ -34,12 +34,9 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--sample-rate 96000" ]; - description = '' + description = lib.mdDoc '' Extra arguments, added verbatim to the fluidsynth command. See - - fluidsynth.conf - 1 - . + {manpage}`fluidsynth.conf(1)`. ''; }; }; diff --git a/modules/services/fnott.nix b/modules/services/fnott.nix index 43be5d71..636f9f49 100644 --- a/modules/services/fnott.nix +++ b/modules/services/fnott.nix @@ -13,22 +13,22 @@ in { options = { services.fnott = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' fnott, a lightweight Wayland notification daemon for wlroots-based compositors - ''; + ''); package = mkOption { type = types.package; default = pkgs.fnott; defaultText = literalExpression "pkgs.fnott"; - description = "Package providing fnott."; + description = lib.mdDoc "Package providing {command}`fnott`."; }; extraFlags = mkOption { type = types.listOf types.str; default = [ ]; example = [ "-s" ]; - description = '' + description = lib.mdDoc '' Extra arguments to use for executing fnott. ''; }; @@ -37,14 +37,14 @@ in { type = types.either types.str types.path; default = "${config.xdg.configHome}/fnott/fnott.ini"; defaultText = "$XDG_CONFIG_HOME/fnott/fnott.ini"; - description = '' + description = lib.mdDoc '' Path to the configuration file read by fnott. - + Note that environment variables in the path won't be properly expanded. - + The configuration specified under - will be generated and - written to $XDG_CONFIG_HOME/fnott/fnott.ini + {option}`services.fnott.settings` will be generated and + written to {file}`$XDG_CONFIG_HOME/fnott/fnott.ini` regardless of this option. This allows using a mutable configuration file generated from the immutable one, useful in scenarios where live reloading is desired. ''; @@ -53,16 +53,12 @@ in { settings = mkOption { type = iniFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/fnott/fnott.ini. - + {file}`$XDG_CONFIG_HOME/fnott/fnott.ini`. + See - - fnott.ini - 5 - for a list of available options and + {manpage}`fnott.ini(5)` for a list of available options and for an example configuration. ''; example = literalExpression '' diff --git a/modules/services/fusuma.nix b/modules/services/fusuma.nix index c48cf5a9..dce59c36 100644 --- a/modules/services/fusuma.nix +++ b/modules/services/fusuma.nix @@ -59,14 +59,14 @@ in { meta.maintainers = [ hm.maintainers.iosmanthus ]; options.services.fusuma = { - enable = mkEnableOption - "the fusuma systemd service to automatically enable touchpad gesture"; + enable = mkEnableOption (lib.mdDoc + "the fusuma systemd service to automatically enable touchpad gesture"); package = mkOption { type = types.package; default = pkgs.fusuma; defaultText = literalExpression "pkgs.fusuma"; - description = "Package providing fusuma."; + description = lib.mdDoc "Package providing {command}`fusuma`."; }; settings = mkOption { @@ -89,7 +89,7 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' YAML config that will override the default fusuma configuration. ''; }; @@ -101,7 +101,7 @@ in { example = literalExpression '' with pkgs; [ coreutils xdotool ]; ''; - description = '' + description = lib.mdDoc '' Extra packages needs to bring to the scope of fusuma service. ''; }; diff --git a/modules/services/getmail.nix b/modules/services/getmail.nix index 05950e62..85648a69 100644 --- a/modules/services/getmail.nix +++ b/modules/services/getmail.nix @@ -17,19 +17,19 @@ let in { options = { services.getmail = { - enable = mkEnableOption - "the getmail systemd service to automatically retrieve mail"; + enable = mkEnableOption (lib.mdDoc + "the getmail systemd service to automatically retrieve mail"); frequency = mkOption { type = types.str; default = "*:0/5"; example = "hourly"; - description = '' - The refresh frequency. Check man systemd.time for + description = lib.mdDoc '' + The refresh frequency. Check `man systemd.time` for more information on the syntax. If you use a gpg-agent in combination with the passwordCommand, keep the poll frequency below the cache-ttl value (as set by the - default) to avoid pinentry asking + `default`) to avoid pinentry asking permanently for a password. ''; }; diff --git a/modules/services/git-sync.nix b/modules/services/git-sync.nix index 42f8c4cc..7c5409b0 100644 --- a/modules/services/git-sync.nix +++ b/modules/services/git-sync.nix @@ -35,21 +35,21 @@ let internal = true; default = name; type = types.str; - description = "The name that should be given to this unit."; + description = lib.mdDoc "The name that should be given to this unit."; }; path = mkOption { type = types.path; - description = "The path at which to sync the repository"; + description = lib.mdDoc "The path at which to sync the repository"; }; uri = mkOption { type = types.str; example = "git+ssh://user@example.com:/~[user]/path/to/repo.git"; - description = '' + description = lib.mdDoc '' The URI of the remote to be synchronized. This is only used in the event that the directory does not already exist. See - + for the supported URIs. ''; }; @@ -57,7 +57,7 @@ let interval = mkOption { type = types.int; default = 500; - description = '' + description = lib.mdDoc '' The interval, specified in seconds, at which the synchronization will be triggered even without filesystem changes. ''; @@ -70,20 +70,20 @@ in { options = { services.git-sync = { - enable = mkEnableOption "git-sync services"; + enable = mkEnableOption (lib.mdDoc "git-sync services"); package = mkOption { type = types.package; default = pkgs.git-sync; defaultText = literalExpression "pkgs.git-sync"; - description = '' - Package containing the git-sync program. + description = lib.mdDoc '' + Package containing the {command}`git-sync` program. ''; }; repositories = mkOption { type = with types; attrsOf repositoryType; - description = '' + description = lib.mdDoc '' The repositories that should be synchronized. ''; }; diff --git a/modules/services/gnome-keyring.nix b/modules/services/gnome-keyring.nix index 460e4abd..ad543a38 100644 --- a/modules/services/gnome-keyring.nix +++ b/modules/services/gnome-keyring.nix @@ -11,12 +11,12 @@ in { options = { services.gnome-keyring = { - enable = mkEnableOption "GNOME Keyring"; + enable = mkEnableOption (lib.mdDoc "GNOME Keyring"); components = mkOption { type = types.listOf (types.enum [ "pkcs11" "secrets" "ssh" ]); default = [ ]; - description = '' + description = lib.mdDoc '' The GNOME keyring components to start. If empty then the default set of components will be started. ''; diff --git a/modules/services/gpg-agent.nix b/modules/services/gpg-agent.nix index 39e93669..5c96aecc 100644 --- a/modules/services/gpg-agent.nix +++ b/modules/services/gpg-agent.nix @@ -75,12 +75,12 @@ in { options = { services.gpg-agent = { - enable = mkEnableOption "GnuPG private key agent"; + enable = mkEnableOption (lib.mdDoc "GnuPG private key agent"); defaultCacheTtl = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Set the time a cache entry is valid to the given number of seconds. ''; @@ -89,7 +89,7 @@ in { defaultCacheTtlSsh = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Set the time a cache entry used for SSH keys is valid to the given number of seconds. ''; @@ -98,7 +98,7 @@ in { maxCacheTtl = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Set the maximum time a cache entry is valid to n seconds. After this time a cache entry will be expired even if it has been accessed recently or has been set using gpg-preset-passphrase. The default is @@ -109,7 +109,7 @@ in { maxCacheTtlSsh = mkOption { type = types.nullOr types.int; default = null; - description = '' + description = lib.mdDoc '' Set the maximum time a cache entry used for SSH keys is valid to n seconds. After this time a cache entry will be expired even if it has been accessed recently or has been set using gpg-preset-passphrase. @@ -120,7 +120,7 @@ in { enableSshSupport = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to use the GnuPG key agent for SSH keys. ''; }; @@ -128,7 +128,7 @@ in { sshKeys = mkOption { type = types.nullOr (types.listOf types.str); default = null; - description = '' + description = lib.mdDoc '' Which GPG keys (by keygrip) to expose as SSH keys. ''; }; @@ -136,7 +136,7 @@ in { enableExtraSocket = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable extra socket of the GnuPG key agent (useful for GPG Agent forwarding). ''; @@ -145,7 +145,7 @@ in { verbose = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to produce verbose output. ''; }; @@ -153,22 +153,22 @@ in { grabKeyboardAndMouse = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Tell the pinentry to grab the keyboard and mouse. This option should in general be used to avoid X-sniffing attacks. When disabled, this option passes - setting to gpg-agent. + {option}`no-grab` setting to gpg-agent. ''; }; enableScDaemon = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Make use of the scdaemon tool. This option has the effect of enabling the ability to do smartcard operations. When disabled, this option passes - setting to gpg-agent. + {option}`disable-scdaemon` setting to gpg-agent. ''; }; @@ -179,7 +179,7 @@ in { allow-emacs-pinentry allow-loopback-pinentry ''; - description = '' + description = lib.mdDoc '' Extra configuration lines to append to the gpg-agent configuration file. ''; @@ -189,31 +189,31 @@ in { type = types.nullOr (types.enum pkgs.pinentry.flavors); example = "gnome3"; default = "gtk2"; - description = '' + description = lib.mdDoc '' Which pinentry interface to use. If not - null, it sets - in - gpg-agent.conf. Beware that - pinentry-gnome3 may not work on non-Gnome + `null`, it sets + {option}`pinentry-program` in + {file}`gpg-agent.conf`. Beware that + `pinentry-gnome3` may not work on non-Gnome systems. You can fix it by adding the following to your system configuration: - + ```nix services.dbus.packages = [ pkgs.gcr ]; - - For this reason, the default is gtk2 for + ``` + For this reason, the default is `gtk2` for now. ''; }; - enableBashIntegration = mkEnableOption "Bash integration" // { + enableBashIntegration = mkEnableOption (lib.mdDoc "Bash integration") // { default = true; }; - enableZshIntegration = mkEnableOption "Zsh integration" // { + enableZshIntegration = mkEnableOption (lib.mdDoc "Zsh integration") // { default = true; }; - enableFishIntegration = mkEnableOption "Fish integration" // { + enableFishIntegration = mkEnableOption (lib.mdDoc "Fish integration") // { default = true; }; }; diff --git a/modules/services/grobi.nix b/modules/services/grobi.nix index d90b7244..2b45a16f 100644 --- a/modules/services/grobi.nix +++ b/modules/services/grobi.nix @@ -14,17 +14,17 @@ in { options = { services.grobi = { - enable = mkEnableOption "the grobi display setup daemon"; + enable = mkEnableOption (lib.mdDoc "the grobi display setup daemon"); executeAfter = mkOption { type = with types; listOf str; default = [ ]; example = [ "setxkbmap dvorak" ]; - description = '' + description = lib.mdDoc '' Commands to be run after an output configuration was changed. The Nix value declared here will be translated to - JSON and written to the key - in $XDG_CONFIG_HOME/grobi.conf. + JSON and written to the {option}`execute_after` key + in {file}`$XDG_CONFIG_HOME/grobi.conf`. ''; }; @@ -57,14 +57,14 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' These are the rules grobi tries to match to the current output configuration. The rules are evaluated top to bottom, the first matching rule is applied and processing stops. See - + for more information. The Nix value declared here will be - translated to JSON and written to the - key in $XDG_CONFIG_HOME/grobi.conf. + translated to JSON and written to the {option}`rules` + key in {file}`$XDG_CONFIG_HOME/grobi.conf`. ''; }; }; diff --git a/modules/services/gromit-mpx.nix b/modules/services/gromit-mpx.nix index 7a85cf76..92956d75 100644 --- a/modules/services/gromit-mpx.nix +++ b/modules/services/gromit-mpx.nix @@ -63,7 +63,7 @@ let device = mkOption { type = types.str; example = "default"; - description = '' + description = lib.mdDoc '' Use this tool with the given xinput device. The device with the name default works with any input. ''; @@ -73,29 +73,29 @@ let type = types.enum [ "pen" "eraser" "recolor" ]; default = "pen"; example = "eraser"; - description = "Which type of tool this is."; + description = lib.mdDoc "Which type of tool this is."; }; color = mkOption { type = types.str; default = "red"; example = "#ff00ff"; - description = "The stroke (or recolor) color of the tool."; + description = lib.mdDoc "The stroke (or recolor) color of the tool."; }; size = mkOption { type = types.ints.positive; default = 5; example = 3; - description = "The tool size."; + description = lib.mdDoc "The tool size."; }; arrowSize = mkOption { type = types.nullOr types.ints.positive; default = null; example = 2; - description = '' - If not null, automatically draw an arrow + description = lib.mdDoc '' + If not `null`, automatically draw an arrow at the end of a stroke with the given size. ''; }; @@ -104,7 +104,7 @@ let type = types.listOf (types.enum modsAndButtons); default = [ ]; example = [ "SHIFT" ]; - description = '' + description = lib.mdDoc '' Only activate this tool if the given modifiers are also active. ''; }; @@ -115,22 +115,22 @@ in { meta.maintainers = [ maintainers.pjones ]; options.services.gromit-mpx = { - enable = mkEnableOption "Gromit-MPX annotation tool"; + enable = mkEnableOption (lib.mdDoc "Gromit-MPX annotation tool"); package = mkOption { type = types.package; default = pkgs.gromit-mpx; defaultText = "pkgs.gromit-mpx"; - description = "The gromit-mpx package to use."; + description = lib.mdDoc "The gromit-mpx package to use."; }; hotKey = mkOption { type = with types; nullOr (either str ints.positive); default = "F9"; example = "Insert"; - description = '' + description = lib.mdDoc '' A keysym or raw keycode that toggles the activation state of - gromit-mpx. Set to null to disable the + gromit-mpx. Set to `null` to disable the hotkey in which case you'll have to activate gromit-mpx manually using the command line. ''; @@ -139,10 +139,10 @@ in { undoKey = mkOption { type = with types; nullOr (either str ints.positive); default = "F10"; - description = '' + description = lib.mdDoc '' A keysym or raw keycode that causes gromit-mpx to undo the last stroke. Use this key along with the shift key to redo an - undone stoke. Set to null to disable the + undone stoke. Set to `null` to disable the undo hotkey. ''; }; @@ -153,7 +153,7 @@ in { }; default = 0.75; example = 1.0; - description = "Opacity of the drawing overlay."; + description = lib.mdDoc "Opacity of the drawing overlay."; }; tools = mkOption { @@ -194,7 +194,7 @@ in { modifiers = [ "3" ]; } ]; - description = '' + description = lib.mdDoc '' Tool definitions for gromit-mpx to use. ''; }; diff --git a/modules/services/home-manager-auto-upgrade.nix b/modules/services/home-manager-auto-upgrade.nix index d4851322..3b8baa8e 100644 --- a/modules/services/home-manager-auto-upgrade.nix +++ b/modules/services/home-manager-auto-upgrade.nix @@ -13,22 +13,19 @@ in { options = { services.home-manager.autoUpgrade = { - enable = lib.mkEnableOption '' + enable = lib.mkEnableOption (lib.mdDoc '' the Home Manager upgrade service that periodically updates your Nix - channels before running home-manager switch''; + channels before running `home-manager switch`''); frequency = lib.mkOption { type = lib.types.str; example = "weekly"; - description = '' + description = lib.mdDoc '' The interval at which the Home Manager auto upgrade is run. This value is passed to the systemd timer configuration - as the OnCalendar option. + as the `OnCalendar` option. The format is described in - - systemd.time - 7 - . + {manpage}`systemd.time(7)`. ''; }; }; diff --git a/modules/services/hound.nix b/modules/services/hound.nix index ff18a381..b031fa04 100644 --- a/modules/services/hound.nix +++ b/modules/services/hound.nix @@ -21,25 +21,25 @@ in { meta.maintainers = [ maintainers.adisbladis ]; options.services.hound = { - enable = mkEnableOption "hound"; + enable = mkEnableOption (lib.mdDoc "hound"); maxConcurrentIndexers = mkOption { type = types.ints.positive; default = 2; - description = "Limit the amount of concurrent indexers."; + description = lib.mdDoc "Limit the amount of concurrent indexers."; }; databasePath = mkOption { type = types.path; default = "${config.xdg.dataHome}/hound"; defaultText = "$XDG_DATA_HOME/hound"; - description = "The Hound database path."; + description = lib.mdDoc "The Hound database path."; }; listenAddress = mkOption { type = types.str; default = "localhost:6080"; - description = "Listen address of the Hound daemon."; + description = lib.mdDoc "Listen address of the Hound daemon."; }; repositories = mkOption { @@ -54,7 +54,7 @@ in { }; } ''; - description = "The repository configuration."; + description = lib.mdDoc "The repository configuration."; }; }; diff --git a/modules/services/imapnotify-accounts.nix b/modules/services/imapnotify-accounts.nix index e437f94e..6dec9dca 100644 --- a/modules/services/imapnotify-accounts.nix +++ b/modules/services/imapnotify-accounts.nix @@ -4,13 +4,13 @@ with lib; { options.imapnotify = { - enable = mkEnableOption "imapnotify"; + enable = mkEnableOption (lib.mdDoc "imapnotify"); onNotify = mkOption { type = with types; either str (attrsOf str); default = ""; example = "\${pkgs.isync}/bin/mbsync test-%s"; - description = "Shell commands to run on any event."; + description = lib.mdDoc "Shell commands to run on any event."; }; onNotifyPost = mkOption { @@ -20,21 +20,22 @@ with lib; mail = "\${pkgs.notmuch}/bin/notmuch new && \${pkgs.libnotify}/bin/notify-send 'New mail arrived'"; }; - description = "Shell commands to run after onNotify event."; + description = lib.mdDoc "Shell commands to run after onNotify event."; }; boxes = mkOption { type = types.listOf types.str; default = [ ]; example = [ "Inbox" "[Gmail]/MyLabel" ]; - description = "IMAP folders to watch."; + description = lib.mdDoc "IMAP folders to watch."; }; extraConfig = mkOption { type = let jsonFormat = pkgs.formats.json { }; in jsonFormat.type; default = { }; example = { wait = 10; }; - description = "Additional configuration to add for this account."; + description = + lib.mdDoc "Additional configuration to add for this account."; }; }; } diff --git a/modules/services/imapnotify.nix b/modules/services/imapnotify.nix index a79cba35..9c9fdd0e 100644 --- a/modules/services/imapnotify.nix +++ b/modules/services/imapnotify.nix @@ -87,14 +87,14 @@ in { options = { services.imapnotify = { - enable = mkEnableOption "imapnotify"; + enable = mkEnableOption (lib.mdDoc "imapnotify"); package = mkOption { type = types.package; default = pkgs.goimapnotify; defaultText = literalExpression "pkgs.goimapnotify"; example = literalExpression "pkgs.imapnotify"; - description = "The imapnotify package to use"; + description = lib.mdDoc "The imapnotify package to use"; }; }; diff --git a/modules/services/kanshi.nix b/modules/services/kanshi.nix index cdef4c72..f3ed0b7f 100644 --- a/modules/services/kanshi.nix +++ b/modules/services/kanshi.nix @@ -11,24 +11,21 @@ let criteria = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The criteria can either be an output name, an output description or "*". The latter can be used to match any output. On - - sway - 1 - , + {manpage}`sway(1)`, output names and descriptions can be obtained via - swaymsg -t get_outputs. + `swaymsg -t get_outputs`. ''; }; status = mkOption { type = types.nullOr (types.enum [ "enable" "disable" ]); default = null; - description = '' + description = lib.mdDoc '' Enables or disables the specified output. ''; }; @@ -37,9 +34,9 @@ let type = types.nullOr types.str; default = null; example = "1920x1080@60Hz"; - description = '' + description = lib.mdDoc '' <width>x<height>[@<rate>[Hz]] - + Configures the specified output to use the specified mode. Modes are a combination of width and height (in pixels) and a refresh rate (in Hz) that your display can be configured to use. @@ -50,9 +47,9 @@ let type = types.nullOr types.str; default = null; example = "1600,0"; - description = '' + description = lib.mdDoc '' <x>,<y> - + Places the output at the specified position in the global coordinates space. ''; @@ -62,7 +59,7 @@ let type = types.nullOr types.float; default = null; example = 2; - description = '' + description = lib.mdDoc '' Scales the output by the specified scale factor. ''; }; @@ -79,7 +76,7 @@ let "flipped-270" ]); default = null; - description = '' + description = lib.mdDoc '' Sets the output transform. ''; }; @@ -98,7 +95,7 @@ let outputs = mkOption { type = types.listOf outputModule; default = [ ]; - description = '' + description = lib.mdDoc '' Outputs configuration. ''; }; @@ -108,7 +105,7 @@ let default = [ ]; example = "[ \${pkg.sway}/bin/swaymsg workspace 1, move workspace to eDP-1 ]"; - description = '' + description = lib.mdDoc '' Commands executed after the profile is successfully applied. Note that if you provide multiple commands, they will be executed asynchronously with no guaranteed ordering. @@ -131,14 +128,14 @@ in { meta.maintainers = [ hm.maintainers.nurelin ]; options.services.kanshi = { - enable = mkEnableOption - "kanshi, a Wayland daemon that automatically configures outputs"; + enable = mkEnableOption (lib.mdDoc + "kanshi, a Wayland daemon that automatically configures outputs"); package = mkOption { type = types.package; default = pkgs.kanshi; defaultText = literalExpression "pkgs.kanshi"; - description = '' + description = lib.mdDoc '' kanshi derivation to use. ''; }; @@ -146,7 +143,7 @@ in { profiles = mkOption { type = types.attrsOf profileModule; default = { }; - description = '' + description = lib.mdDoc '' List of profiles. ''; example = literalExpression '' @@ -174,7 +171,7 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra configuration lines to append to the kanshi configuration file. ''; @@ -183,7 +180,7 @@ in { systemdTarget = mkOption { type = types.str; default = "sway-session.target"; - description = '' + description = lib.mdDoc '' Systemd target to bind to. ''; }; diff --git a/modules/services/kbfs.nix b/modules/services/kbfs.nix index 4f1bfd8b..d9cd87e5 100644 --- a/modules/services/kbfs.nix +++ b/modules/services/kbfs.nix @@ -9,14 +9,14 @@ let in { options = { services.kbfs = { - enable = mkEnableOption "Keybase File System"; + enable = mkEnableOption (lib.mdDoc "Keybase File System"); mountPoint = mkOption { type = types.str; default = "keybase"; - description = '' + description = lib.mdDoc '' Mount point for the Keybase filesystem, relative to - HOME. + {env}`HOME`. ''; }; @@ -24,7 +24,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "-label kbfs" "-mount-type normal" ]; - description = '' + description = lib.mdDoc '' Additional flags to pass to the Keybase filesystem on launch. ''; }; diff --git a/modules/services/kdeconnect.nix b/modules/services/kdeconnect.nix index 0c6aac31..74374557 100644 --- a/modules/services/kdeconnect.nix +++ b/modules/services/kdeconnect.nix @@ -12,12 +12,13 @@ in { options = { services.kdeconnect = { - enable = mkEnableOption "KDE connect"; + enable = mkEnableOption (lib.mdDoc "KDE connect"); indicator = mkOption { type = types.bool; default = false; - description = "Whether to enable kdeconnect-indicator service."; + description = + lib.mdDoc "Whether to enable kdeconnect-indicator service."; }; }; diff --git a/modules/services/keepassx.nix b/modules/services/keepassx.nix index 7f858236..a4e85eca 100644 --- a/modules/services/keepassx.nix +++ b/modules/services/keepassx.nix @@ -7,7 +7,7 @@ with lib; options = { services.keepassx = { - enable = mkEnableOption "the KeePassX password manager"; + enable = mkEnableOption (lib.mdDoc "the KeePassX password manager"); }; }; diff --git a/modules/services/keybase.nix b/modules/services/keybase.nix index f6e40086..8165fa09 100644 --- a/modules/services/keybase.nix +++ b/modules/services/keybase.nix @@ -7,7 +7,7 @@ let cfg = config.services.keybase; in { - options.services.keybase.enable = mkEnableOption "Keybase"; + options.services.keybase.enable = mkEnableOption (lib.mdDoc "Keybase"); config = mkIf cfg.enable { assertions = [ diff --git a/modules/services/keynav.nix b/modules/services/keynav.nix index d83252e5..8cef4ae0 100644 --- a/modules/services/keynav.nix +++ b/modules/services/keynav.nix @@ -7,7 +7,7 @@ let cfg = config.services.keynav; in { - options.services.keynav = { enable = mkEnableOption "keynav"; }; + options.services.keynav = { enable = mkEnableOption (lib.mdDoc "keynav"); }; config = mkIf cfg.enable { assertions = [ diff --git a/modules/services/lieer.nix b/modules/services/lieer.nix index e5f30761..dda6a230 100644 --- a/modules/services/lieer.nix +++ b/modules/services/lieer.nix @@ -52,7 +52,7 @@ in { meta.maintainers = [ maintainers.tadfisher ]; options.services.lieer.enable = - mkEnableOption "lieer Gmail synchronization service"; + mkEnableOption (lib.mdDoc "lieer Gmail synchronization service"); config = mkIf cfg.enable { assertions = [ diff --git a/modules/services/listenbrainz-mpd.nix b/modules/services/listenbrainz-mpd.nix index 1ac25c6a..cd7fc08b 100644 --- a/modules/services/listenbrainz-mpd.nix +++ b/modules/services/listenbrainz-mpd.nix @@ -13,16 +13,16 @@ in { meta.maintainers = [ lib.maintainers.Scrumplex ]; options.services.listenbrainz-mpd = { - enable = mkEnableOption "listenbrainz-mpd"; + enable = mkEnableOption (lib.mdDoc "listenbrainz-mpd"); package = mkPackageOptionMD pkgs "listenbrainz-mpd" { }; settings = mkOption { type = tomlFormat.type; default = { }; - description = '' + description = lib.mdDoc '' Configuration for listenbrainz-mpd written to - $XDG_CONFIG_HOME/listenbrainz-mpd/config.toml. + {file}`$XDG_CONFIG_HOME/listenbrainz-mpd/config.toml`. ''; example = { submission.tokenFile = "/run/secrets/listenbrainz-mpd"; }; }; diff --git a/modules/services/lorri.nix b/modules/services/lorri.nix index 85b75682..8e94a793 100644 --- a/modules/services/lorri.nix +++ b/modules/services/lorri.nix @@ -10,15 +10,16 @@ in { meta.maintainers = [ maintainers.gerschtli ]; options.services.lorri = { - enable = mkEnableOption "lorri build daemon"; + enable = mkEnableOption (lib.mdDoc "lorri build daemon"); - enableNotifications = mkEnableOption "lorri build notifications"; + enableNotifications = + mkEnableOption (lib.mdDoc "lorri build notifications"); package = mkOption { type = types.package; default = pkgs.lorri; defaultText = literalExpression "pkgs.lorri"; - description = "Which lorri package to install."; + description = lib.mdDoc "Which lorri package to install."; }; nixPackage = mkOption { @@ -26,7 +27,7 @@ in { default = pkgs.nix; defaultText = literalExpression "pkgs.nix"; example = literalExpression "pkgs.nixVersions.unstable"; - description = "Which nix package to use."; + description = lib.mdDoc "Which nix package to use."; }; }; diff --git a/modules/services/mako.nix b/modules/services/mako.nix index be36c435..a528d4df 100644 --- a/modules/services/mako.nix +++ b/modules/services/mako.nix @@ -14,21 +14,21 @@ in { options = { services.mako = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Mako, lightweight notification daemon for Wayland - ''; + ''); package = mkOption { type = types.package; default = pkgs.mako; defaultText = literalExpression "pkgs.mako"; - description = "The mako package to use."; + description = lib.mdDoc "The mako package to use."; }; maxVisible = mkOption { default = 5; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set maximum number of visible notifications. Set -1 to show all. ''; }; @@ -37,7 +37,7 @@ in { default = "-time"; type = types.nullOr (types.enum [ "+time" "-time" "+priority" "-priority" ]); - description = '' + description = lib.mdDoc '' Sorts incoming notifications by time and/or priority in ascending(+) or descending(-) order. ''; @@ -46,7 +46,7 @@ in { output = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Show notifications on the specified output. If empty, notifications will appear on the focused output. Requires the compositor to support the Wayland protocol xdg-output-unstable-v1 version 2. @@ -57,7 +57,7 @@ in { default = "top"; type = types.nullOr (types.enum [ "background" "bottom" "top" "overlay" ]); - description = '' + description = lib.mdDoc '' Arrange mako at the specified layer, relative to normal windows. Supported values are background, bottom, top, and overlay. Using overlay will cause notifications to be displayed above fullscreen @@ -77,7 +77,7 @@ in { "bottom-left" "center" ]); - description = '' + description = lib.mdDoc '' Show notifications at the specified position on the output. Supported values are top-right, top-center, top-left, bottom-right, bottom-center, bottom-left, and center. @@ -87,7 +87,7 @@ in { font = mkOption { default = "monospace 10"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Font to use, in Pango format. ''; }; @@ -95,7 +95,7 @@ in { backgroundColor = mkOption { default = "#285577FF"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set popup background color to a specific color, represented in hex color code. ''; @@ -104,7 +104,7 @@ in { textColor = mkOption { default = "#FFFFFFFF"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set popup text color to a specific color, represented in hex color code. ''; @@ -113,7 +113,7 @@ in { width = mkOption { default = 300; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set width of notification popups in specified number of pixels. ''; }; @@ -121,7 +121,7 @@ in { height = mkOption { default = 100; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set maximum height of notification popups. Notifications whose text takes up less space are shrunk to fit. ''; @@ -130,7 +130,7 @@ in { margin = mkOption { default = "10"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set margin of each edge specified in pixels. Specify single value to apply margin on all sides. Two comma-separated values will set vertical and horizontal edges separately. Four comma-separated will @@ -143,7 +143,7 @@ in { padding = mkOption { default = "5"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set padding of each edge specified in pixels. Specify single value to apply margin on all sides. Two comma-separated values will set vertical and horizontal edges separately. Four comma-separated will @@ -156,7 +156,7 @@ in { borderSize = mkOption { default = 1; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set popup border size to the specified number of pixels. ''; }; @@ -164,7 +164,7 @@ in { borderColor = mkOption { default = "#4C7899FF"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set popup border color to a specific color, represented in hex color code. ''; @@ -173,7 +173,7 @@ in { borderRadius = mkOption { default = 0; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set popup corner radius to the specified number of pixels. ''; }; @@ -181,12 +181,12 @@ in { progressColor = mkOption { default = "over #5588AAFF"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set popup progress indicator color to a specific color, represented in hex color code. To draw the progress indicator on top of the background color, use the - over attribute. To replace the background - color, use the source attribute (this can + `over` attribute. To replace the background + color, use the `source` attribute (this can be useful when the notification is semi-transparent). ''; }; @@ -194,7 +194,7 @@ in { icons = mkOption { default = true; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Whether or not to show icons in notifications. ''; }; @@ -202,7 +202,7 @@ in { maxIconSize = mkOption { default = 64; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set maximum icon size to the specified number of pixels. ''; }; @@ -210,15 +210,15 @@ in { iconPath = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Paths to search for icons when a notification specifies a name instead of a full path. Colon-delimited. This approximates the search algorithm used by the XDG Icon Theme Specification, but does not support any of the theme metadata. Therefore, if you want to search parent themes, you'll need to add them to the path manually. - - The /usr/share/icons/hicolor and - /usr/share/pixmaps directories are + + The {file}`/usr/share/icons/hicolor` and + {file}`/usr/share/pixmaps` directories are always searched. ''; }; @@ -226,7 +226,7 @@ in { markup = mkOption { default = true; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' If 1, enable Pango markup. If 0, disable Pango markup. If enabled, Pango markup will be interpreted in your format specifier and in the body of notifications. @@ -236,7 +236,7 @@ in { actions = mkOption { default = true; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' Applications may request an action to be associated with activating a notification. Disabling this will cause mako to ignore these requests. ''; @@ -245,7 +245,7 @@ in { format = mkOption { default = "%s\\n%b"; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' Set notification format string to format. See FORMAT SPECIFIERS for more information. To change this for grouped notifications, set it within a grouped criteria. @@ -255,7 +255,7 @@ in { defaultTimeout = mkOption { default = 0; type = types.nullOr types.int; - description = '' + description = lib.mdDoc '' Set the default timeout to timeout in milliseconds. To disable the timeout, set it to zero. ''; @@ -264,7 +264,7 @@ in { ignoreTimeout = mkOption { default = false; type = types.nullOr types.bool; - description = '' + description = lib.mdDoc '' If set, mako will ignore the expire timeout sent by notifications and use the one provided by default-timeout instead. ''; @@ -273,7 +273,7 @@ in { groupBy = mkOption { default = null; type = types.nullOr types.str; - description = '' + description = lib.mdDoc '' A comma-separated list of criteria fields that will be compared to other visible notifications to determine if this one should form a group with them. All listed criteria must be exactly equal for two @@ -288,7 +288,7 @@ in { [urgency=low] border-color=#b8bb26 ''; - description = "Additional configuration."; + description = lib.mdDoc "Additional configuration."; }; }; }; diff --git a/modules/services/mbsync.nix b/modules/services/mbsync.nix index bdeda0ec..b70f2c09 100644 --- a/modules/services/mbsync.nix +++ b/modules/services/mbsync.nix @@ -13,26 +13,23 @@ in { meta.maintainers = [ maintainers.pjones ]; options.services.mbsync = { - enable = mkEnableOption "mbsync"; + enable = mkEnableOption (lib.mdDoc "mbsync"); package = mkOption { type = types.package; default = pkgs.isync; defaultText = literalExpression "pkgs.isync"; example = literalExpression "pkgs.isync"; - description = "The package to use for the mbsync binary."; + description = lib.mdDoc "The package to use for the mbsync binary."; }; frequency = mkOption { type = types.str; default = "*:0/5"; - description = '' + description = lib.mdDoc '' How often to run mbsync. This value is passed to the systemd timer configuration as the onCalendar option. See - - systemd.time - 7 - + {manpage}`systemd.time(7)` for more information about the format. ''; }; @@ -40,7 +37,7 @@ in { verbose = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether mbsync should produce verbose output. ''; }; @@ -48,9 +45,9 @@ in { configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Optional configuration file to link to use instead of - the default file (~/.mbsyncrc). + the default file ({file}`~/.mbsyncrc`). ''; }; @@ -58,7 +55,7 @@ in { type = types.nullOr types.str; default = null; example = "mkdir -p %h/mail"; - description = '' + description = lib.mdDoc '' An optional command to run before mbsync executes. This is useful for creating the directories mbsync is going to use. ''; @@ -68,7 +65,7 @@ in { type = types.nullOr types.str; default = null; example = "\${pkgs.mu}/bin/mu index"; - description = '' + description = lib.mdDoc '' An optional command to run after mbsync executes successfully. This is useful for running mailbox indexing tools. ''; diff --git a/modules/services/megasync.nix b/modules/services/megasync.nix index 283a7280..19b4e2e0 100644 --- a/modules/services/megasync.nix +++ b/modules/services/megasync.nix @@ -11,7 +11,7 @@ in { options = { services.megasync = { - enable = mkEnableOption "Megasync client"; + enable = mkEnableOption (lib.mdDoc "Megasync client"); package = mkPackageOptionMD pkgs "megasync" { }; }; diff --git a/modules/services/mopidy.nix b/modules/services/mopidy.nix index f5064c51..ea2b8f4b 100644 --- a/modules/services/mopidy.nix +++ b/modules/services/mopidy.nix @@ -52,14 +52,14 @@ in { meta.maintainers = [ hm.maintainers.foo-dogsquared ]; options.services.mopidy = { - enable = mkEnableOption "Mopidy music player daemon"; + enable = mkEnableOption (lib.mdDoc "Mopidy music player daemon"); extensionPackages = mkOption { type = with types; listOf package; default = [ ]; example = literalExpression "with pkgs; [ mopidy-spotify mopidy-mpd mopidy-mpris ]"; - description = '' + description = lib.mdDoc '' Mopidy extensions that should be loaded by the service. ''; }; @@ -92,11 +92,11 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/mopidy/mopidy.conf. - - See for + {file}`$XDG_CONFIG_HOME/mopidy/mopidy.conf`. + + See for more details. ''; }; @@ -104,7 +104,7 @@ in { extraConfigFiles = mkOption { default = [ ]; type = types.listOf types.path; - description = '' + description = lib.mdDoc '' Extra configuration files read by Mopidy when the service starts. Later files in the list override earlier configuration files and structured settings. diff --git a/modules/services/mpd-discord-rpc.nix b/modules/services/mpd-discord-rpc.nix index 50bc824b..e311d076 100644 --- a/modules/services/mpd-discord-rpc.nix +++ b/modules/services/mpd-discord-rpc.nix @@ -10,7 +10,7 @@ in { meta.maintainers = [ maintainers.kranzes ]; options.services.mpd-discord-rpc = { - enable = mkEnableOption "the mpd-discord-rpc service"; + enable = mkEnableOption (lib.mdDoc "the mpd-discord-rpc service"); settings = mkOption { type = tomlFormat.type; @@ -24,9 +24,9 @@ in { }; } ''; - description = '' - Configuration included in config.toml. - For available options see + description = lib.mdDoc '' + Configuration included in `config.toml`. + For available options see ''; }; @@ -34,7 +34,7 @@ in { type = types.package; default = pkgs.mpd-discord-rpc; defaultText = literalExpression "pkgs.mpd-discord-rpc"; - description = "mpd-discord-rpc package to use."; + description = lib.mdDoc "mpd-discord-rpc package to use."; }; }; diff --git a/modules/services/mpd-mpris.nix b/modules/services/mpd-mpris.nix index 3a502d45..7207d139 100644 --- a/modules/services/mpd-mpris.nix +++ b/modules/services/mpd-mpris.nix @@ -25,7 +25,7 @@ in { options.services.mpd-mpris = { enable = lib.mkEnableOption - "mpd-mpris: An implementation of the MPRIS protocol for MPD"; + (lib.mdDoc "mpd-mpris: An implementation of the MPRIS protocol for MPD"); package = lib.mkPackageOptionMD pkgs "mpd-mpris" { }; @@ -34,10 +34,10 @@ in { type = lib.types.bool; default = config.services.mpd.enable; defaultText = lib.literalExpression "config.services.mpd.enable"; - description = '' + description = lib.mdDoc '' Whether to configure for the local MPD daemon. If - true the network, - host, and port + `true` the `network`, + `host`, and `port` settings are ignored. ''; }; @@ -45,9 +45,9 @@ in { network = lib.mkOption { type = with lib.types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' The network used to dial to the MPD server. Check - + for available values (most common are "tcp" and "unix") ''; }; @@ -56,13 +56,14 @@ in { type = with lib.types; nullOr str; default = null; example = "192.168.1.1"; - description = "The address where MPD is listening for connections."; + description = + lib.mdDoc "The address where MPD is listening for connections."; }; port = lib.mkOption { type = with lib.types; nullOr port; default = null; - description = '' + description = lib.mdDoc '' The port number where MPD is listening for connections. ''; }; @@ -70,7 +71,7 @@ in { password = lib.mkOption { type = with lib.types; nullOr str; default = null; - description = '' + description = lib.mdDoc '' The password to connect to MPD. ''; }; diff --git a/modules/services/mpd.nix b/modules/services/mpd.nix index 3d3ce1b9..ee72b332 100644 --- a/modules/services/mpd.nix +++ b/modules/services/mpd.nix @@ -36,7 +36,7 @@ in { enable = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to enable MPD, the music player daemon. ''; }; @@ -45,7 +45,7 @@ in { type = types.package; default = pkgs.mpd; defaultText = "pkgs.mpd"; - description = '' + description = lib.mdDoc '' The MPD package to run. ''; }; @@ -58,11 +58,11 @@ in { undefined otherwise ''; apply = toString; # Prevent copies to Nix store. - description = '' + description = lib.mdDoc '' The directory where mpd reads music from. - - If is - true then the defined XDG music directory is used. + + If [](#opt-xdg.userDirs.enable) is + `true` then the defined XDG music directory is used. Otherwise, you must explicitly specify a value. ''; }; @@ -72,7 +72,7 @@ in { default = "${cfg.dataDir}/playlists"; defaultText = "\${dataDir}/playlists"; apply = toString; # Prevent copies to Nix store. - description = '' + description = lib.mdDoc '' The directory where mpd stores playlists. ''; }; @@ -80,15 +80,12 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Extra directives added to to the end of MPD's configuration - file, mpd.conf. Basic configuration + file, {file}`mpd.conf`. Basic configuration like file location and uid/gid is added automatically to the beginning of the file. For available options see - - mpd.conf - 5 - . + {manpage}`mpd.conf(5)`. ''; }; @@ -96,7 +93,7 @@ in { type = types.listOf types.str; default = [ ]; example = [ "--verbose" ]; - description = '' + description = lib.mdDoc '' Extra command-line arguments to pass to MPD. ''; }; @@ -106,7 +103,7 @@ in { default = "${config.xdg.dataHome}/${name}"; defaultText = "$XDG_DATA_HOME/mpd"; apply = toString; # Prevent copies to Nix store. - description = '' + description = lib.mdDoc '' The directory where MPD stores its state, tag cache, playlists etc. ''; @@ -116,7 +113,7 @@ in { startWhenNeeded = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable systemd socket activation. ''; }; @@ -125,16 +122,16 @@ in { type = types.str; default = "127.0.0.1"; example = "any"; - description = '' + description = lib.mdDoc '' The address for the daemon to listen on. - Use any to listen on all addresses. + Use `any` to listen on all addresses. ''; }; port = mkOption { type = types.port; default = 6600; - description = '' + description = lib.mdDoc '' The TCP port on which the the daemon will listen. ''; }; @@ -145,9 +142,9 @@ in { type = types.nullOr types.str; default = "${cfg.dataDir}/tag_cache"; defaultText = "\${dataDir}/tag_cache"; - description = '' + description = lib.mdDoc '' The path to MPD's database. If set to - null the parameter is omitted from the + `null` the parameter is omitted from the configuration. ''; }; diff --git a/modules/services/mpdris2.nix b/modules/services/mpdris2.nix index 79f2709f..54cfc579 100644 --- a/modules/services/mpdris2.nix +++ b/modules/services/mpdris2.nix @@ -35,15 +35,15 @@ in { meta.maintainers = [ maintainers.pjones ]; options.services.mpdris2 = { - enable = mkEnableOption "mpDris2 the MPD to MPRIS2 bridge"; - notifications = mkEnableOption "song change notifications"; - multimediaKeys = mkEnableOption "multimedia key support"; + enable = mkEnableOption (lib.mdDoc "mpDris2 the MPD to MPRIS2 bridge"); + notifications = mkEnableOption (lib.mdDoc "song change notifications"); + multimediaKeys = mkEnableOption (lib.mdDoc "multimedia key support"); package = mkOption { type = types.package; default = pkgs.mpdris2; defaultText = literalExpression "pkgs.mpdris2"; - description = "The mpDris2 package to use."; + description = lib.mdDoc "The mpDris2 package to use."; }; mpd = { @@ -52,14 +52,15 @@ in { default = config.services.mpd.network.listenAddress; defaultText = "config.services.mpd.network.listenAddress"; example = "192.168.1.1"; - description = "The address where MPD is listening for connections."; + description = + lib.mdDoc "The address where MPD is listening for connections."; }; port = mkOption { type = types.port; default = config.services.mpd.network.port; defaultText = "config.services.mpd.network.port"; - description = '' + description = lib.mdDoc '' The port number where MPD is listening for connections. ''; }; @@ -68,7 +69,7 @@ in { type = types.nullOr types.path; default = config.services.mpd.musicDirectory; defaultText = "config.services.mpd.musicDirectory"; - description = '' + description = lib.mdDoc '' If set, mpDris2 will use this directory to access music artwork. ''; }; @@ -76,7 +77,7 @@ in { password = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The password to connect to MPD. ''; }; diff --git a/modules/services/mpris-proxy.nix b/modules/services/mpris-proxy.nix index 9996b137..3ac455d7 100644 --- a/modules/services/mpris-proxy.nix +++ b/modules/services/mpris-proxy.nix @@ -9,8 +9,8 @@ let in { meta.maintainers = [ maintainers.thibautmarty ]; - options.services.mpris-proxy.enable = mkEnableOption - "a proxy forwarding Bluetooth MIDI controls via MPRIS2 to control media players"; + options.services.mpris-proxy.enable = mkEnableOption (lib.mdDoc + "a proxy forwarding Bluetooth MIDI controls via MPRIS2 to control media players"); config = mkIf cfg.enable { assertions = [ diff --git a/modules/services/muchsync.nix b/modules/services/muchsync.nix index 8c9e2701..91cda9f9 100644 --- a/modules/services/muchsync.nix +++ b/modules/services/muchsync.nix @@ -12,14 +12,11 @@ let frequency = mkOption { type = types.str; default = "*:0/5"; - description = '' - How often to run muchsync. This + description = lib.mdDoc '' + How often to run {command}`muchsync`. This value is passed to the systemd timer configuration as the - OnCalendar option. See - - systemd.time - 7 - + `OnCalendar` option. See + {manpage}`systemd.time(7)` for more information about the format. ''; }; @@ -28,10 +25,10 @@ let type = types.str; default = "${pkgs.openssh}/bin/ssh -CTaxq"; defaultText = "ssh -CTaxq"; - description = '' - Specifies a command line to pass to /bin/sh + description = lib.mdDoc '' + Specifies a command line to pass to {command}`/bin/sh` to execute a command on another machine. - + Note that because this string is passed to the shell, special characters including spaces may need to be escaped. ''; @@ -40,7 +37,7 @@ let upload = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to propagate local changes to the remote. ''; }; @@ -49,16 +46,16 @@ let checkForModifiedFiles = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Check for locally modified files. Without this option, muchsync assumes that files in a maildir are never edited. - - disables certain + + {option}`checkForModifiedFiles` disables certain optimizations so as to make muchsync at least check the timestamp on every file, which will detect modified files at the cost of a longer startup time. - + This option is useful if your software regularly modifies the contents of mail files (e.g., because you are running offlineimap with "synclabels = yes"). @@ -68,9 +65,9 @@ let importNew = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to begin the synchronisation by running - notmuch new locally. + {command}`notmuch new` locally. ''; }; }; @@ -78,7 +75,7 @@ let remote = { host = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Remote SSH host to synchronize with. ''; }; @@ -87,7 +84,7 @@ let type = types.str; default = ""; defaultText = "$PATH/muchsync"; - description = '' + description = lib.mdDoc '' Specifies the path to muchsync on the server. Ordinarily, muchsync should be in the default PATH on the server so this option is not required. @@ -100,16 +97,16 @@ let checkForModifiedFiles = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Check for modified files on the remote side. Without this option, muchsync assumes that files in a maildir are never edited. - - disables certain + + {option}`checkForModifiedFiles` disables certain optimizations so as to make muchsync at least check the timestamp on every file, which will detect modified files at the cost of a longer startup time. - + This option is useful if your software regularly modifies the contents of mail files (e.g., because you are running offlineimap with "synclabels = yes"). @@ -119,9 +116,9 @@ let importNew = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to begin the synchronisation by running - notmuch new on the remote side. + {command}`notmuch new` on the remote side. ''; }; }; @@ -143,7 +140,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Muchsync remotes to synchronise with. ''; }; diff --git a/modules/services/network-manager-applet.nix b/modules/services/network-manager-applet.nix index f4abe86e..d82a6f78 100644 --- a/modules/services/network-manager-applet.nix +++ b/modules/services/network-manager-applet.nix @@ -11,7 +11,7 @@ in { options = { services.network-manager-applet = { - enable = mkEnableOption "the Network Manager applet"; + enable = mkEnableOption (lib.mdDoc "the Network Manager applet"); }; }; diff --git a/modules/services/nextcloud-client.nix b/modules/services/nextcloud-client.nix index b436488d..c004569c 100644 --- a/modules/services/nextcloud-client.nix +++ b/modules/services/nextcloud-client.nix @@ -9,20 +9,21 @@ let in { options = { services.nextcloud-client = { - enable = mkEnableOption "Nextcloud Client"; + enable = mkEnableOption (lib.mdDoc "Nextcloud Client"); package = mkOption { type = types.package; default = pkgs.nextcloud-client; defaultText = literalExpression "pkgs.nextcloud-client"; - description = "The package to use for the nextcloud client binary."; + description = + lib.mdDoc "The package to use for the nextcloud client binary."; }; startInBackground = mkOption { type = types.bool; default = false; description = - "Whether to start the Nextcloud client in the background."; + lib.mdDoc "Whether to start the Nextcloud client in the background."; }; }; }; diff --git a/modules/services/notify-osd.nix b/modules/services/notify-osd.nix index 6a75ce6e..38b57690 100644 --- a/modules/services/notify-osd.nix +++ b/modules/services/notify-osd.nix @@ -11,14 +11,14 @@ in { options = { services.notify-osd = { - enable = mkEnableOption "notify-osd"; + enable = mkEnableOption (lib.mdDoc "notify-osd"); package = mkOption { type = types.package; default = pkgs.notify-osd; defaultText = literalExpression "pkgs.notify-osd"; - description = '' - Package containing the notify-osd program. + description = lib.mdDoc '' + Package containing the {command}`notify-osd` program. ''; }; }; diff --git a/modules/services/opensnitch-ui.nix b/modules/services/opensnitch-ui.nix index a086554c..fcecc7a7 100644 --- a/modules/services/opensnitch-ui.nix +++ b/modules/services/opensnitch-ui.nix @@ -11,7 +11,9 @@ in { meta.maintainers = [ maintainers.onny ]; options = { - services.opensnitch-ui = { enable = mkEnableOption "Opensnitch client"; }; + services.opensnitch-ui = { + enable = mkEnableOption (lib.mdDoc "Opensnitch client"); + }; }; config = mkIf cfg.enable { diff --git a/modules/services/owncloud-client.nix b/modules/services/owncloud-client.nix index d9c69929..7f4f9a54 100644 --- a/modules/services/owncloud-client.nix +++ b/modules/services/owncloud-client.nix @@ -9,7 +9,7 @@ let in { options = { services.owncloud-client = { - enable = mkEnableOption "Owncloud Client"; + enable = mkEnableOption (lib.mdDoc "Owncloud Client"); package = mkPackageOptionMD pkgs "owncloud-client" { }; }; diff --git a/modules/services/pantalaimon.nix b/modules/services/pantalaimon.nix index d833d453..de1e39b0 100644 --- a/modules/services/pantalaimon.nix +++ b/modules/services/pantalaimon.nix @@ -11,15 +11,15 @@ in { options = { services.pantalaimon = { - enable = mkEnableOption - "Pantalaimon, an E2EE aware proxy daemon for matrix clients"; + enable = mkEnableOption (lib.mdDoc + "Pantalaimon, an E2EE aware proxy daemon for matrix clients"); package = mkOption { type = types.package; default = pkgs.pantalaimon; defaultText = literalExpression "pkgs.pantalaimon"; - description = - "Package providing the pantalaimon executable to use."; + description = lib.mdDoc + "Package providing the {command}`pantalaimon` executable to use."; }; settings = mkOption { @@ -39,15 +39,12 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/pantalaimon/pantalaimon.conf. - - See or - - pantalaimon - 5 - + {file}`$XDG_CONFIG_HOME/pantalaimon/pantalaimon.conf`. + + See or + {manpage}`pantalaimon(5)` for options. ''; }; diff --git a/modules/services/parcellite.nix b/modules/services/parcellite.nix index 39b81e86..ccec6b44 100644 --- a/modules/services/parcellite.nix +++ b/modules/services/parcellite.nix @@ -10,13 +10,13 @@ in { meta.maintainers = [ maintainers.gleber ]; options.services.parcellite = { - enable = mkEnableOption "Parcellite"; + enable = mkEnableOption (lib.mdDoc "Parcellite"); extraOptions = mkOption { type = types.listOf types.str; default = [ ]; example = [ "--no-icon" ]; - description = '' + description = lib.mdDoc '' Command line arguments passed to Parcellite. ''; }; @@ -26,7 +26,7 @@ in { default = pkgs.parcellite; defaultText = literalExpression "pkgs.parcellite"; example = literalExpression "pkgs.clipit"; - description = "Parcellite derivation to use."; + description = lib.mdDoc "Parcellite derivation to use."; }; }; diff --git a/modules/services/pass-secret-service.nix b/modules/services/pass-secret-service.nix index 907477bf..5086ae32 100644 --- a/modules/services/pass-secret-service.nix +++ b/modules/services/pass-secret-service.nix @@ -10,7 +10,7 @@ in { meta.maintainers = with maintainers; [ cab404 cyntheticfox ]; options.services.pass-secret-service = { - enable = mkEnableOption "Pass libsecret service"; + enable = mkEnableOption (lib.mdDoc "Pass libsecret service"); package = mkPackageOptionMD pkgs "pass-secret-service" { }; @@ -19,11 +19,11 @@ in { default = null; defaultText = "$HOME/.password-store"; example = "/home/user/.local/share/password-store"; - description = '' + description = lib.mdDoc '' Absolute path to password store. Defaults to - $HOME/.password-store if the - module is not enabled, and - if it is. + {file}`$HOME/.password-store` if the + {option}`programs.password-store` module is not enabled, and + {option}`programs.password-store.settings.PASSWORD_STORE_DIR` if it is. ''; }; }; diff --git a/modules/services/password-store-sync.nix b/modules/services/password-store-sync.nix index c8dbe808..fd7ddee1 100644 --- a/modules/services/password-store-sync.nix +++ b/modules/services/password-store-sync.nix @@ -11,22 +11,19 @@ in { meta.maintainers = with maintainers; [ pacien ]; options.services.password-store-sync = { - enable = mkEnableOption "Password store periodic sync"; + enable = mkEnableOption (lib.mdDoc "Password store periodic sync"); frequency = mkOption { type = types.str; default = "*:0/5"; - description = '' + description = lib.mdDoc '' How often to synchronise the password store git repository with its default upstream. - + This value is passed to the systemd timer configuration as the - onCalendar option. + `onCalendar` option. See - - systemd.time - 7 - + {manpage}`systemd.time(7)` for more information about the format. ''; }; diff --git a/modules/services/pasystray.nix b/modules/services/pasystray.nix index 32922ad0..e33891b8 100644 --- a/modules/services/pasystray.nix +++ b/modules/services/pasystray.nix @@ -6,7 +6,9 @@ with lib; meta.maintainers = [ hm.maintainers.pltanton ]; options = { - services.pasystray = { enable = mkEnableOption "PulseAudio system tray"; }; + services.pasystray = { + enable = mkEnableOption (lib.mdDoc "PulseAudio system tray"); + }; }; config = mkIf config.services.pasystray.enable { diff --git a/modules/services/pbgopy.nix b/modules/services/pbgopy.nix index 487aa4f3..d0ea6d20 100644 --- a/modules/services/pbgopy.nix +++ b/modules/services/pbgopy.nix @@ -18,13 +18,13 @@ in { meta.maintainers = [ maintainers.ivar ]; options.services.pbgopy = { - enable = mkEnableOption "pbgopy"; + enable = mkEnableOption (lib.mdDoc "pbgopy"); port = mkOption { type = types.port; default = 9090; example = 8080; - description = '' + description = lib.mdDoc '' The port to host the pbgopy server on. ''; }; @@ -33,8 +33,8 @@ in { type = types.str; default = "24h"; example = "10m"; - description = '' - The TTL for the cache. Use "0s" to disable it. + description = lib.mdDoc '' + The TTL for the cache. Use `"0s"` to disable it. ''; }; @@ -42,7 +42,7 @@ in { type = types.nullOr types.str; default = null; example = "user:pass"; - description = '' + description = lib.mdDoc '' Basic HTTP authentication's username and password. Both the username and password are escaped. ''; diff --git a/modules/services/picom.nix b/modules/services/picom.nix index 66f707c0..485d3031 100644 --- a/modules/services/picom.nix +++ b/modules/services/picom.nix @@ -66,12 +66,12 @@ in { ]; options.services.picom = { - enable = mkEnableOption "Picom X11 compositor"; + enable = mkEnableOption (lib.mdDoc "Picom X11 compositor"); fade = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Fade windows in and out. ''; }; @@ -80,7 +80,7 @@ in { type = types.ints.positive; default = 10; example = 5; - description = '' + description = lib.mdDoc '' Time between fade animation step (in ms). ''; }; @@ -89,7 +89,7 @@ in { type = pairOf (types.numbers.between 1.0e-2 1); default = [ 2.8e-2 3.0e-2 ]; example = [ 4.0e-2 4.0e-2 ]; - description = '' + description = lib.mdDoc '' Opacity change between fade steps (in and out). ''; }; @@ -98,16 +98,16 @@ in { type = types.listOf types.str; default = [ ]; example = [ "window_type *= 'menu'" "name ~= 'Firefox$'" "focused = 1" ]; - description = '' + description = lib.mdDoc '' List of conditions of windows that should not be faded. - See picom(1) man page for more examples. + See `picom(1)` man page for more examples. ''; }; shadow = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Draw window shadows. ''; }; @@ -116,7 +116,7 @@ in { type = pairOf types.int; default = [ (-15) (-15) ]; example = [ (-10) (-15) ]; - description = '' + description = lib.mdDoc '' Left and right offset for shadows (in pixels). ''; }; @@ -125,7 +125,7 @@ in { type = types.numbers.between 0 1; default = 0.75; example = 0.8; - description = '' + description = lib.mdDoc '' Window shadows opacity. ''; }; @@ -134,9 +134,9 @@ in { type = types.listOf types.str; default = [ ]; example = [ "window_type *= 'menu'" "name ~= 'Firefox$'" "focused = 1" ]; - description = '' + description = lib.mdDoc '' List of conditions of windows that should have no shadow. - See picom(1) man page for more examples. + See `picom(1)` man page for more examples. ''; }; @@ -144,7 +144,7 @@ in { type = types.numbers.between 0 1; default = 1.0; example = 0.8; - description = '' + description = lib.mdDoc '' Opacity of active windows. ''; }; @@ -153,7 +153,7 @@ in { type = types.numbers.between 0.1 1; default = 1.0; example = 0.8; - description = '' + description = lib.mdDoc '' Opacity of inactive windows. ''; }; @@ -162,7 +162,7 @@ in { type = types.numbers.between 0 1; default = 1.0; example = 0.8; - description = '' + description = lib.mdDoc '' Opacity of dropdown and popup menu. ''; }; @@ -180,7 +180,7 @@ in { } ''; example = { }; - description = '' + description = lib.mdDoc '' Rules for specific window types. ''; }; @@ -192,7 +192,7 @@ in { "95:class_g = 'URxvt' && !_NET_WM_STATE@:32a" "0:_NET_WM_STATE@:32a *= '_NET_WM_STATE_HIDDEN'" ]; - description = '' + description = lib.mdDoc '' Rules that control the opacity of windows, in format PERCENT:PATTERN. ''; }; @@ -200,15 +200,15 @@ in { backend = mkOption { type = types.enum [ "egl" "glx" "xrender" "xr_glx_hybrid" ]; default = "xrender"; - description = '' - Backend to use: egl, glx, xrender or xr_glx_hybrid. + description = lib.mdDoc '' + Backend to use: `egl`, `glx`, `xrender` or `xr_glx_hybrid`. ''; }; vSync = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Enable vertical synchronization. ''; }; @@ -217,7 +217,7 @@ in { type = with types; listOf str; default = [ ]; example = literalExpression ''[ "--legacy-backends" ]''; - description = '' + description = lib.mdDoc '' Extra arguments to be passed to the picom executable. ''; }; @@ -227,7 +227,7 @@ in { default = pkgs.picom; defaultText = literalExpression "pkgs.picom"; example = literalExpression "pkgs.picom"; - description = '' + description = lib.mdDoc '' Picom derivation to use. ''; }; @@ -261,10 +261,10 @@ in { deviation = 5.0; }; ''; - description = '' + description = lib.mdDoc '' Picom settings. Use this option to configure Picom settings not exposed in a NixOS option or to bypass one. For the available options see the - CONFIGURATION FILES section at picom(1). + CONFIGURATION FILES section at `picom(1)`. ''; }; }; diff --git a/modules/services/plan9port.nix b/modules/services/plan9port.nix index 24980472..47ed8c27 100644 --- a/modules/services/plan9port.nix +++ b/modules/services/plan9port.nix @@ -11,9 +11,9 @@ in { options.services.plan9port = { fontsrv.enable = - mkEnableOption "the Plan 9 file system access to host fonts"; - plumber.enable = - mkEnableOption "the Plan 9 file system for interprocess messaging"; + mkEnableOption (lib.mdDoc "the Plan 9 file system access to host fonts"); + plumber.enable = mkEnableOption + (lib.mdDoc "the Plan 9 file system for interprocess messaging"); }; config = mkIf (cfg.fontsrv.enable || cfg.plumber.enable) { diff --git a/modules/services/playerctld.nix b/modules/services/playerctld.nix index 5fed8f2b..6d168406 100644 --- a/modules/services/playerctld.nix +++ b/modules/services/playerctld.nix @@ -10,13 +10,13 @@ in { meta.maintainers = [ hm.maintainers.fendse ]; options.services.playerctld = { - enable = mkEnableOption "playerctld daemon"; + enable = mkEnableOption (lib.mdDoc "playerctld daemon"); package = mkOption { type = types.package; default = pkgs.playerctl; defaultText = literalExpression "pkgs.playerctl"; - description = "The playerctl package to use."; + description = lib.mdDoc "The playerctl package to use."; }; }; diff --git a/modules/services/plex-mpv-shim.nix b/modules/services/plex-mpv-shim.nix index b5fb6218..9c43703a 100644 --- a/modules/services/plex-mpv-shim.nix +++ b/modules/services/plex-mpv-shim.nix @@ -12,13 +12,13 @@ in { options = { services.plex-mpv-shim = { - enable = mkEnableOption "Plex mpv shim"; + enable = mkEnableOption (lib.mdDoc "Plex mpv shim"); package = mkOption { type = types.package; default = pkgs.plex-mpv-shim; defaultText = literalExpression "pkgs.plex-mpv-shim"; - description = "The package to use for the Plex mpv shim."; + description = lib.mdDoc "The package to use for the Plex mpv shim."; }; settings = mkOption { @@ -35,10 +35,10 @@ in { auto_transcode = true; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/plex-mpv-shim/config.json. See - + {file}`$XDG_CONFIG_HOME/plex-mpv-shim/config.json`. See + for the configuration documentation. ''; }; diff --git a/modules/services/polybar.nix b/modules/services/polybar.nix index d008c580..866cf184 100644 --- a/modules/services/polybar.nix +++ b/modules/services/polybar.nix @@ -70,13 +70,13 @@ let in { options = { services.polybar = { - enable = mkEnableOption "Polybar status bar"; + enable = mkEnableOption (lib.mdDoc "Polybar status bar"); package = mkOption { type = types.package; default = pkgs.polybar; defaultText = literalExpression "pkgs.polybar"; - description = "Polybar package to install."; + description = lib.mdDoc "Polybar package to install."; example = literalExpression '' pkgs.polybar.override { i3GapsSupport = true; @@ -91,10 +91,10 @@ in { type = types.coercedTo types.path (p: { "section/base" = { include-file = "${p}"; }; }) (types.attrsOf (types.attrsOf eitherStrBoolIntList)); - description = '' + description = lib.mdDoc '' Polybar configuration. Can be either path to a file, or set of attributes that will be used to create the final configuration. - See also for a more nix-friendly format. + See also {option}`services.polybar.settings` for a more nix-friendly format. ''; default = { }; example = literalExpression '' @@ -172,7 +172,7 @@ in { extraConfig = mkOption { type = types.lines; - description = "Additional configuration to add."; + description = lib.mdDoc "Additional configuration to add."; default = ""; example = '' [module/date] @@ -187,10 +187,10 @@ in { script = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' This script will be used to start the polybars. Set all necessary environment variables here and start all bars. - It can be assumed that polybar executable is in the PATH. + It can be assumed that {command}`polybar` executable is in the {env}`PATH`. Note, this script must start all bars in the background and then terminate. ''; diff --git a/modules/services/poweralertd.nix b/modules/services/poweralertd.nix index bc02dead..d2576786 100644 --- a/modules/services/poweralertd.nix +++ b/modules/services/poweralertd.nix @@ -8,7 +8,7 @@ in { meta.maintainers = [ maintainers.thibautmarty ]; options.services.poweralertd.enable = - mkEnableOption "the Upower-powered power alertd"; + mkEnableOption (lib.mdDoc "the Upower-powered power alertd"); config = mkIf cfg.enable { assertions = [ diff --git a/modules/services/pueue.nix b/modules/services/pueue.nix index 3733ef39..87f190c3 100644 --- a/modules/services/pueue.nix +++ b/modules/services/pueue.nix @@ -12,7 +12,8 @@ in { meta.maintainers = [ maintainers.AndersonTorres ]; options.services.pueue = { - enable = mkEnableOption "Pueue, CLI process scheduler and manager"; + enable = + mkEnableOption (lib.mdDoc "Pueue, CLI process scheduler and manager"); package = mkPackageOptionMD pkgs "pueue" { }; @@ -26,9 +27,9 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/pueue/pueue.yml. + {file}`$XDG_CONFIG_HOME/pueue/pueue.yml`. ''; }; }; diff --git a/modules/services/pulseeffects.nix b/modules/services/pulseeffects.nix index 0181e39b..a1a6a0cf 100644 --- a/modules/services/pulseeffects.nix +++ b/modules/services/pulseeffects.nix @@ -12,25 +12,25 @@ in { meta.maintainers = [ maintainers.jonringer ]; options.services.pulseeffects = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' Pulseeffects daemon Note, it is necessary to add - + ```nix programs.dconf.enable = true; - - to your system configuration for the daemon to work correctly''; + ``` + to your system configuration for the daemon to work correctly''); package = mkOption { type = types.package; default = pkgs.pulseeffects-legacy; defaultText = literalExpression "pkgs.pulseeffects-legacy"; - description = "Pulseeffects package to use."; + description = lib.mdDoc "Pulseeffects package to use."; }; preset = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' Which preset to use when starting pulseeffects. Will likely need to launch pulseeffects to initially create preset. ''; diff --git a/modules/services/random-background.nix b/modules/services/random-background.nix index d7eed87b..d8b479e1 100644 --- a/modules/services/random-background.nix +++ b/modules/services/random-background.nix @@ -30,7 +30,7 @@ in { imageDirectory = mkOption { type = types.str; example = "%h/backgrounds"; - description = '' + description = lib.mdDoc '' The directory of images from which a background should be chosen. Should be formatted in a way understood by systemd, e.g., '%h' is the home directory. @@ -40,14 +40,15 @@ in { display = mkOption { type = types.enum [ "center" "fill" "max" "scale" "tile" ]; default = "fill"; - description = "Display background images according to this option."; + description = + lib.mdDoc "Display background images according to this option."; }; interval = mkOption { default = null; type = types.nullOr types.str; example = "1h"; - description = '' + description = lib.mdDoc '' The duration between changing background image, set to null to only set background when logging in. Should be formatted as a duration understood by systemd. @@ -57,7 +58,7 @@ in { enableXinerama = mkOption { default = true; type = types.bool; - description = '' + description = lib.mdDoc '' Will place a separate image per screen when enabled, otherwise a single image will be stretched across all screens. diff --git a/modules/services/recoll.nix b/modules/services/recoll.nix index 794a5de8..6224fa67 100644 --- a/modules/services/recoll.nix +++ b/modules/services/recoll.nix @@ -78,14 +78,14 @@ in { meta.maintainers = [ maintainers.foo-dogsquared ]; options.services.recoll = { - enable = mkEnableOption "Recoll file index service"; + enable = mkEnableOption (lib.mdDoc "Recoll file index service"); package = mkOption { type = types.package; default = pkgs.recoll; defaultText = literalExpression "pkgs.recoll"; - description = '' - Package providing the recoll binary. + description = lib.mdDoc '' + Package providing the `recoll` binary. ''; example = literalExpression "(pkgs.recoll.override { withGui = false; })"; }; @@ -94,28 +94,22 @@ in { type = types.str; default = "hourly"; example = "00/2:00"; - description = '' + description = lib.mdDoc '' When or how often the periodic update should run. Must be the format described from - - systemd.time - 7 - . + {manpage}`systemd.time(7)`. ''; }; settings = mkOption { type = settingsFormat.type; default = { }; - description = '' + description = lib.mdDoc '' The configuration to be written at - ''${config.services.recoll.configDir}/recoll.conf. + {file}`''${config.services.recoll.configDir}/recoll.conf`. See - - recoll - 5 - for more details about the configuration. + {manpage}`recoll(5)` for more details about the configuration. ''; example = literalExpression '' { @@ -139,9 +133,9 @@ in { default = "${config.home.homeDirectory}/.recoll"; defaultText = literalExpression "\${config.home.homeDirectory}/.recoll"; example = literalExpression "\${config.xdg.configHome}/recoll"; - description = '' + description = lib.mdDoc '' The directory to contain Recoll configuration files. This will be set - as RECOLL_CONFDIR. + as `RECOLL_CONFDIR`. ''; }; }; diff --git a/modules/services/redshift-gammastep/lib/options.nix b/modules/services/redshift-gammastep/lib/options.nix index 7b02150e..bbdbe25b 100644 --- a/modules/services/redshift-gammastep/lib/options.nix +++ b/modules/services/redshift-gammastep/lib/options.nix @@ -29,13 +29,13 @@ in { ]; options = { - enable = mkEnableOption programName; + enable = mkEnableOption (lib.mdDoc programName); dawnTime = mkOption { type = types.nullOr types.str; default = null; example = "6:00-7:45"; - description = '' + description = lib.mdDoc '' Set the time interval of dawn manually. The times must be specified as HH:MM in 24-hour format. ''; @@ -45,7 +45,7 @@ in { type = types.nullOr types.str; default = null; example = "18:35-20:15"; - description = '' + description = lib.mdDoc '' Set the time interval of dusk manually. The times must be specified as HH:MM in 24-hour format. ''; @@ -54,9 +54,9 @@ in { latitude = mkOption { type = with types; nullOr (either str float); default = null; - description = '' - Your current latitude, between -90.0 and - 90.0. Must be provided along with + description = lib.mdDoc '' + Your current latitude, between `-90.0` and + `90.0`. Must be provided along with longitude. ''; }; @@ -64,9 +64,9 @@ in { longitude = mkOption { type = with types; nullOr (either str float); default = null; - description = '' - Your current longitude, between -180.0 and - 180.0. Must be provided along with + description = lib.mdDoc '' + Your current longitude, between `-180.0` and + `180.0`. Must be provided along with latitude. ''; }; @@ -74,10 +74,10 @@ in { provider = mkOption { type = types.enum [ "manual" "geoclue2" ]; default = "manual"; - description = '' + description = lib.mdDoc '' The location provider to use for determining your location. If set to - manual you must also provide latitude/longitude. - If set to geoclue2, you must also enable the global + `manual` you must also provide latitude/longitude. + If set to `geoclue2`, you must also enable the global geoclue2 service. ''; }; @@ -86,17 +86,17 @@ in { day = mkOption { type = types.int; default = 5500; - description = '' + description = lib.mdDoc '' Colour temperature to use during the day, between - 1000 and 25000 K. + `1000` and `25000` K. ''; }; night = mkOption { type = types.int; default = 3700; - description = '' + description = lib.mdDoc '' Colour temperature to use at night, between - 1000 and 25000 K. + `1000` and `25000` K. ''; }; }; @@ -105,18 +105,18 @@ in { type = types.package; default = defaultPackage; defaultText = literalExpression examplePackage; - description = '' + description = lib.mdDoc '' ${programName} derivation to use. ''; }; - enableVerboseLogging = mkEnableOption "verbose service logging"; + enableVerboseLogging = mkEnableOption (lib.mdDoc "verbose service logging"); tray = mkOption { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Start the ${appletExecutable} tray applet. ''; }; @@ -134,13 +134,10 @@ in { }; }; ''; - description = '' + description = lib.mdDoc '' The configuration to pass to ${programName}. Available options for ${programName} described in - - ${moduleName} - 1 - . + {manpage}`${moduleName}(1)`. ''; }; }; diff --git a/modules/services/rsibreak.nix b/modules/services/rsibreak.nix index 351632a0..7040b4a0 100644 --- a/modules/services/rsibreak.nix +++ b/modules/services/rsibreak.nix @@ -9,7 +9,7 @@ let in { options.services.rsibreak = { - enable = mkEnableOption "rsibreak"; + enable = mkEnableOption (lib.mdDoc "rsibreak"); }; diff --git a/modules/services/safeeyes.nix b/modules/services/safeeyes.nix index 4ce7afad..04812357 100644 --- a/modules/services/safeeyes.nix +++ b/modules/services/safeeyes.nix @@ -11,7 +11,7 @@ in { options = { services.safeeyes = { - enable = mkEnableOption "The Safe Eyes OSGI service"; + enable = mkEnableOption (lib.mdDoc "The Safe Eyes OSGI service"); package = mkPackageOptionMD pkgs "safeeyes" { }; }; diff --git a/modules/services/screen-locker.nix b/modules/services/screen-locker.nix index 4fa98008..56279f0d 100644 --- a/modules/services/screen-locker.nix +++ b/modules/services/screen-locker.nix @@ -23,23 +23,23 @@ in { ]; options.services.screen-locker = { - enable = mkEnableOption "screen locker for X session"; + enable = mkEnableOption (lib.mdDoc "screen locker for X session"); lockCmd = mkOption { type = types.str; - description = "Locker command to run."; + description = lib.mdDoc "Locker command to run."; example = "\${pkgs.i3lock}/bin/i3lock -n -c 000000"; }; inactiveInterval = mkOption { type = types.int; default = 10; - description = '' + description = lib.mdDoc '' Inactive time interval in minutes after which session will be locked. The minimum is 1 minute, and the maximum is 1 hour. - If is true, it will use this setting. - See . - Otherwise, this will be used with xset to configure + If {option}`xautolock.enable` is true, it will use this setting. + See . + Otherwise, this will be used with {command}`xset` to configure the X server's screensaver timeout. ''; }; @@ -48,32 +48,32 @@ in { enable = mkOption { type = types.bool; default = true; - description = "Use xautolock for time-based locking."; + description = lib.mdDoc "Use xautolock for time-based locking."; }; package = mkOption { type = types.package; default = pkgs.xautolock; - description = '' - Package providing the xautolock binary. + description = lib.mdDoc '' + Package providing the {command}`xautolock` binary. ''; }; detectSleep = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to reset xautolock timers when awaking from sleep. - No effect if is false. + No effect if {option}`xautolock.enable` is false. ''; }; extraOptions = mkOption { type = types.listOf types.str; default = [ ]; - description = '' - Extra command-line arguments to pass to xautolock. - No effect if is false. + description = lib.mdDoc '' + Extra command-line arguments to pass to {command}`xautolock`. + No effect if {option}`xautolock.enable` is false. ''; }; }; @@ -82,25 +82,25 @@ in { package = mkOption { type = types.package; default = pkgs.xss-lock; - description = '' - Package providing the xss-lock binary. + description = lib.mdDoc '' + Package providing the {command}`xss-lock` binary. ''; }; extraOptions = mkOption { type = types.listOf types.str; default = [ ]; - description = '' - Extra command-line arguments to pass to xss-lock. + description = lib.mdDoc '' + Extra command-line arguments to pass to {command}`xss-lock`. ''; }; screensaverCycle = mkOption { type = types.int; default = 600; - description = '' + description = lib.mdDoc '' The X server's screensaver cycle value expressed as seconds. - This will be used with xset to configure + This will be used with {command}`xset` to configure the cycle along with timeout. ''; }; diff --git a/modules/services/sctd.nix b/modules/services/sctd.nix index 54cf53e4..8bb77a03 100644 --- a/modules/services/sctd.nix +++ b/modules/services/sctd.nix @@ -7,18 +7,15 @@ with lib; options = { services.sctd = { - enable = mkEnableOption "sctd"; + enable = mkEnableOption (lib.mdDoc "sctd"); baseTemperature = mkOption { type = types.ints.between 2500 9000; default = 4500; - description = '' + description = lib.mdDoc '' The base color temperature used by sctd, which should be between 2500 and 9000. See - - sctd - 1 - + {manpage}`sctd(1)` for more details. ''; }; diff --git a/modules/services/spotifyd.nix b/modules/services/spotifyd.nix index b06749a3..702f4a26 100644 --- a/modules/services/spotifyd.nix +++ b/modules/services/spotifyd.nix @@ -12,7 +12,7 @@ let in { options.services.spotifyd = { - enable = mkEnableOption "SpotifyD connect"; + enable = mkEnableOption (lib.mdDoc "SpotifyD connect"); package = mkOption { type = types.package; @@ -20,8 +20,8 @@ in { defaultText = literalExpression "pkgs.spotifyd"; example = literalExpression "(pkgs.spotifyd.override { withKeyring = true; })"; - description = '' - The spotifyd package to use. + description = lib.mdDoc '' + The `spotifyd` package to use. Can be used to specify extensions. ''; }; @@ -29,7 +29,7 @@ in { settings = mkOption { type = tomlFormat.type; default = { }; - description = "Configuration for spotifyd"; + description = lib.mdDoc "Configuration for spotifyd"; example = literalExpression '' { global = { diff --git a/modules/services/ssh-agent.nix b/modules/services/ssh-agent.nix index 16db3232..02cf2c59 100644 --- a/modules/services/ssh-agent.nix +++ b/modules/services/ssh-agent.nix @@ -9,7 +9,7 @@ in { options = { services.ssh-agent = { - enable = lib.mkEnableOption "OpenSSH private key agent"; + enable = lib.mkEnableOption (lib.mdDoc "OpenSSH private key agent"); }; }; diff --git a/modules/services/stalonetray.nix b/modules/services/stalonetray.nix index 172d6dd9..4d34d9ae 100644 --- a/modules/services/stalonetray.nix +++ b/modules/services/stalonetray.nix @@ -9,19 +9,20 @@ let in { options = { services.stalonetray = { - enable = mkEnableOption "Stalonetray system tray"; + enable = mkEnableOption (lib.mdDoc "Stalonetray system tray"); package = mkOption { default = pkgs.stalonetray; defaultText = literalExpression "pkgs.stalonetray"; type = types.package; example = literalExpression "pkgs.stalonetray"; - description = "The package to use for the Stalonetray binary."; + description = + lib.mdDoc "The package to use for the Stalonetray binary."; }; config = mkOption { type = with types; attrsOf (nullOr (either str (either bool int))); - description = '' + description = lib.mdDoc '' Stalonetray configuration as a set of attributes. ''; default = { }; @@ -36,7 +37,8 @@ in { extraConfig = mkOption { type = types.lines; - description = "Additional configuration lines for stalonetrayrc."; + description = + lib.mdDoc "Additional configuration lines for stalonetrayrc."; default = ""; example = '' geometry 3x1-600+0 diff --git a/modules/services/status-notifier-watcher.nix b/modules/services/status-notifier-watcher.nix index c6fe08da..b510eeec 100644 --- a/modules/services/status-notifier-watcher.nix +++ b/modules/services/status-notifier-watcher.nix @@ -11,7 +11,7 @@ in { options = { services.status-notifier-watcher = { - enable = mkEnableOption "Status Notifier Watcher"; + enable = mkEnableOption (lib.mdDoc "Status Notifier Watcher"); package = mkOption { default = pkgs.haskellPackages.status-notifier-item; @@ -19,7 +19,7 @@ in { literalExpression "pkgs.haskellPackages.status-notifier-item"; type = types.package; example = literalExpression "pkgs.haskellPackages.status-notifier-item"; - description = + description = lib.mdDoc "The package to use for the status notifier watcher binary."; }; }; diff --git a/modules/services/swayidle.nix b/modules/services/swayidle.nix index 6e8b55cb..a5e11dd5 100644 --- a/modules/services/swayidle.nix +++ b/modules/services/swayidle.nix @@ -28,18 +28,20 @@ in { timeout = mkOption { type = types.ints.positive; example = 60; - description = "Timeout in seconds."; + description = lib.mdDoc "Timeout in seconds."; }; command = mkOption { type = types.str; - description = "Command to run after timeout seconds of inactivity."; + description = + lib.mdDoc "Command to run after timeout seconds of inactivity."; }; resumeCommand = mkOption { type = with types; nullOr str; default = null; - description = "Command to run when there is activity again."; + description = + lib.mdDoc "Command to run when there is activity again."; }; }; }; @@ -48,24 +50,24 @@ in { options = { event = mkOption { type = types.enum [ "before-sleep" "after-resume" "lock" "unlock" ]; - description = "Event name."; + description = lib.mdDoc "Event name."; }; command = mkOption { type = types.str; - description = "Command to run when event occurs."; + description = lib.mdDoc "Command to run when event occurs."; }; }; }; in { - enable = mkEnableOption "idle manager for Wayland"; + enable = mkEnableOption (lib.mdDoc "idle manager for Wayland"); package = mkOption { type = types.package; default = pkgs.swayidle; defaultText = literalExpression "pkgs.swayidle"; - description = "Swayidle package to install."; + description = lib.mdDoc "Swayidle package to install."; }; timeouts = mkOption { @@ -76,7 +78,7 @@ in { { timeout = 60; command = "${pkgs.swaylock}/bin/swaylock -fF"; } ] ''; - description = "List of commands to run after idle timeout."; + description = lib.mdDoc "List of commands to run after idle timeout."; }; events = mkOption { @@ -88,19 +90,19 @@ in { { event = "lock"; command = "lock"; } ] ''; - description = "Run command on occurrence of a event."; + description = lib.mdDoc "Run command on occurrence of a event."; }; extraArgs = mkOption { type = with types; listOf str; default = [ ]; - description = "Extra arguments to pass to swayidle."; + description = lib.mdDoc "Extra arguments to pass to swayidle."; }; systemdTarget = mkOption { type = types.str; default = "sway-session.target"; - description = '' + description = lib.mdDoc '' Systemd target to bind to. ''; }; diff --git a/modules/services/swayosd.nix b/modules/services/swayosd.nix index 067c104c..737497de 100644 --- a/modules/services/swayosd.nix +++ b/modules/services/swayosd.nix @@ -10,9 +10,9 @@ in { meta.maintainers = [ hm.maintainers.pltanton ]; options.services.swayosd = { - enable = mkEnableOption '' + enable = mkEnableOption (lib.mdDoc '' swayosd, a GTK based on screen display for keyboard shortcuts like - caps-lock and volume''; + caps-lock and volume''); package = mkPackageOption pkgs "swayosd" { }; @@ -20,7 +20,7 @@ in { type = types.nullOr types.ints.unsigned; default = null; example = 120; - description = '' + description = lib.mdDoc '' Sets the maximum volume. ''; }; diff --git a/modules/services/sxhkd.nix b/modules/services/sxhkd.nix index d308c95b..966306f3 100644 --- a/modules/services/sxhkd.nix +++ b/modules/services/sxhkd.nix @@ -19,21 +19,21 @@ in { ]; options.services.sxhkd = { - enable = mkEnableOption "simple X hotkey daemon"; + enable = mkEnableOption (lib.mdDoc "simple X hotkey daemon"); package = mkOption { type = types.package; default = pkgs.sxhkd; defaultText = "pkgs.sxhkd"; description = - "Package containing the sxhkd executable."; + lib.mdDoc "Package containing the {command}`sxhkd` executable."; }; extraOptions = mkOption { type = types.listOf types.str; default = [ ]; description = - "Command line arguments to invoke sxhkd with."; + lib.mdDoc "Command line arguments to invoke {command}`sxhkd` with."; example = literalExpression ''[ "-m 1" ]''; }; @@ -41,7 +41,8 @@ in { type = types.attrsOf (types.nullOr (types.oneOf [ types.str types.path ])); default = { }; - description = "An attribute set that assigns hotkeys to commands."; + description = + lib.mdDoc "An attribute set that assigns hotkeys to commands."; example = literalExpression '' { "super + shift + {r,c}" = "i3-msg {restart,reload}"; @@ -54,7 +55,7 @@ in { extraConfig = mkOption { default = ""; type = types.lines; - description = "Additional configuration to add."; + description = lib.mdDoc "Additional configuration to add."; example = literalExpression '' super + {_,shift +} {1-9,0} i3-msg {workspace,move container to workspace} {1-10} diff --git a/modules/services/syncthing.nix b/modules/services/syncthing.nix index c847985f..8dbe2c77 100644 --- a/modules/services/syncthing.nix +++ b/modules/services/syncthing.nix @@ -20,14 +20,15 @@ in { options = { services.syncthing = { - enable = mkEnableOption "Syncthing continuous file synchronization"; + enable = + mkEnableOption (lib.mdDoc "Syncthing continuous file synchronization"); extraOptions = mkOption { type = types.listOf types.str; default = [ ]; example = [ "--gui-apikey=apiKey" ]; - description = '' - Extra command-line arguments to pass to syncthing. + description = lib.mdDoc '' + Extra command-line arguments to pass to {command}`syncthing`. ''; }; @@ -38,7 +39,8 @@ in { enable = mkOption { type = types.bool; default = false; - description = "Whether to enable a syncthing tray service."; + description = + lib.mdDoc "Whether to enable a syncthing tray service."; }; command = mkOption { @@ -46,7 +48,7 @@ in { default = "syncthingtray"; defaultText = literalExpression "syncthingtray"; example = literalExpression "qsyncthingtray"; - description = "Syncthing tray command to use."; + description = lib.mdDoc "Syncthing tray command to use."; }; package = mkOption { @@ -54,12 +56,12 @@ in { default = pkgs.syncthingtray-minimal; defaultText = literalExpression "pkgs.syncthingtray-minimal"; example = literalExpression "pkgs.qsyncthingtray"; - description = "Syncthing tray package to use."; + description = lib.mdDoc "Syncthing tray package to use."; }; }; }); default = { enable = false; }; - description = "Syncthing tray service configuration."; + description = lib.mdDoc "Syncthing tray service configuration."; }; }; }; diff --git a/modules/services/systembus-notify.nix b/modules/services/systembus-notify.nix index 1b8f1be8..81df5abc 100644 --- a/modules/services/systembus-notify.nix +++ b/modules/services/systembus-notify.nix @@ -7,8 +7,8 @@ with lib; options = { services.systembus-notify = { - enable = - mkEnableOption "systembus-notify - system bus notification daemon"; + enable = mkEnableOption + (lib.mdDoc "systembus-notify - system bus notification daemon"); }; }; diff --git a/modules/services/taffybar.nix b/modules/services/taffybar.nix index 42ca5f7b..9d2c803a 100644 --- a/modules/services/taffybar.nix +++ b/modules/services/taffybar.nix @@ -11,14 +11,14 @@ in { options = { services.taffybar = { - enable = mkEnableOption "Taffybar"; + enable = mkEnableOption (lib.mdDoc "Taffybar"); package = mkOption { default = pkgs.taffybar; defaultText = literalExpression "pkgs.taffybar"; type = types.package; example = literalExpression "pkgs.taffybar"; - description = "The package to use for the Taffybar binary."; + description = lib.mdDoc "The package to use for the Taffybar binary."; }; }; }; diff --git a/modules/services/tahoe-lafs.nix b/modules/services/tahoe-lafs.nix index 105ef3d0..bdf27a25 100644 --- a/modules/services/tahoe-lafs.nix +++ b/modules/services/tahoe-lafs.nix @@ -6,7 +6,7 @@ with lib; meta.maintainers = [ maintainers.rycee ]; options = { - services.tahoe-lafs = { enable = mkEnableOption "Tahoe-LAFS"; }; + services.tahoe-lafs = { enable = mkEnableOption (lib.mdDoc "Tahoe-LAFS"); }; }; config = mkIf config.services.tahoe-lafs.enable { diff --git a/modules/services/taskwarrior-sync.nix b/modules/services/taskwarrior-sync.nix index ddce6d6f..e6f41523 100644 --- a/modules/services/taskwarrior-sync.nix +++ b/modules/services/taskwarrior-sync.nix @@ -10,19 +10,16 @@ in { meta.maintainers = with maintainers; [ minijackson pacien ]; options.services.taskwarrior-sync = { - enable = mkEnableOption "Taskwarrior periodic sync"; + enable = mkEnableOption (lib.mdDoc "Taskwarrior periodic sync"); frequency = mkOption { type = types.str; default = "*:0/5"; - description = '' - How often to run taskwarrior sync. This + description = lib.mdDoc '' + How often to run `taskwarrior sync`. This value is passed to the systemd timer configuration as the - OnCalendar option. See - - systemd.time - 7 - + `OnCalendar` option. See + {manpage}`systemd.time(7)` for more information about the format. ''; }; diff --git a/modules/services/trayer.nix b/modules/services/trayer.nix index 1ac930d4..d6d17959 100644 --- a/modules/services/trayer.nix +++ b/modules/services/trayer.nix @@ -92,14 +92,14 @@ in { options = { services.trayer = { enable = mkEnableOption - "trayer, the lightweight GTK2+ systray for UNIX desktops"; + (lib.mdDoc "trayer, the lightweight GTK2+ systray for UNIX desktops"); package = mkOption { default = pkgs.trayer; defaultText = literalExpression "pkgs.trayer"; type = types.package; example = literalExpression "pkgs.trayer"; - description = "The package to use for the trayer binary."; + description = lib.mdDoc "The package to use for the trayer binary."; }; settings = mkOption { diff --git a/modules/services/twmn.nix b/modules/services/twmn.nix index 1fde0ed7..b6132c16 100644 --- a/modules/services/twmn.nix +++ b/modules/services/twmn.nix @@ -11,10 +11,10 @@ let type = types.ints.between 0 40; default = 38; example = 19; - description = '' + description = lib.mdDoc '' The qt easing-curve animation to use for the animation. See - - QEasingCurve documentation. + [ + QEasingCurve documentation](https://doc.qt.io/qt-5/qeasingcurve.html#Type-enum). ''; }; @@ -22,7 +22,7 @@ let type = types.ints.unsigned; default = 1000; example = 618; - description = "The animation duration in milliseconds."; + description = lib.mdDoc "The animation duration in milliseconds."; }; }; @@ -30,13 +30,14 @@ in { meta.maintainers = [ hm.maintainers.austreelis ]; options.services.twmn = { - enable = mkEnableOption "twmn, a tiling window manager notification daemon"; + enable = mkEnableOption + (lib.mdDoc "twmn, a tiling window manager notification daemon"); duration = mkOption { type = types.ints.unsigned; default = 3000; example = 5000; - description = '' + description = lib.mdDoc '' The time each notification remains visible, in milliseconds. ''; }; @@ -46,9 +47,9 @@ in { default = { }; example = literalExpression ''{ main.activation_command = "\${pkgs.hello}/bin/hello"; }''; - description = '' + description = lib.mdDoc '' Extra configuration options to add to the twmnd config file. See - + for details. ''; }; @@ -57,40 +58,40 @@ in { type = types.str; default = "127.0.0.1"; example = "laptop.lan"; - description = "Host address to listen on for notifications."; + description = lib.mdDoc "Host address to listen on for notifications."; }; icons = { critical = mkOption { type = types.nullOr types.path; default = null; - description = "Path to the critical notifications' icon."; + description = lib.mdDoc "Path to the critical notifications' icon."; }; info = mkOption { type = types.nullOr types.path; default = null; - description = "Path to the informative notifications' icon."; + description = lib.mdDoc "Path to the informative notifications' icon."; }; warning = mkOption { type = types.nullOr types.path; default = null; - description = "Path to the warning notifications' icon."; + description = lib.mdDoc "Path to the warning notifications' icon."; }; }; port = mkOption { type = types.port; default = 9797; - description = "UDP port to listen on for notifications."; + description = lib.mdDoc "UDP port to listen on for notifications."; }; screen = mkOption { type = types.nullOr types.int; default = null; example = 0; - description = '' + description = lib.mdDoc '' Screen number to display notifications on when using a multi-head desktop. ''; @@ -99,7 +100,8 @@ in { soundCommand = mkOption { type = types.str; default = ""; - description = "Command to execute to play a notification's sound."; + description = + lib.mdDoc "Command to execute to play a notification's sound."; }; text = { @@ -107,8 +109,8 @@ in { type = types.str; default = "#999999"; example = "lightgray"; - description = '' - Notification's text color. RGB hex and keywords (e.g. lightgray) + description = lib.mdDoc '' + Notification's text color. RGB hex and keywords (e.g. `lightgray`) are supported. ''; }; @@ -118,8 +120,8 @@ in { type = types.nullOr types.package; default = null; example = literalExpression "pkgs.dejavu_fonts"; - description = '' - Notification text's font package. If null then + description = lib.mdDoc '' + Notification text's font package. If `null` then the font is assumed to already be available in your profile. ''; }; @@ -128,14 +130,14 @@ in { type = types.str; default = "Sans"; example = "Noto Sans"; - description = "Notification text's font family."; + description = lib.mdDoc "Notification text's font family."; }; size = mkOption { type = types.ints.unsigned; default = 13; example = 42; - description = "Notification text's font size."; + description = lib.mdDoc "Notification text's font size."; }; variant = mkOption { @@ -162,7 +164,7 @@ in { ]; default = "medium"; example = "heavy"; - description = "Notification text's font variant."; + description = lib.mdDoc "Notification text's font variant."; }; }; @@ -170,16 +172,16 @@ in { type = types.nullOr types.ints.unsigned; default = null; example = 80; - description = '' + description = lib.mdDoc '' Maximum length of the text before it is cut and suffixed with "...". - Never cuts if null. + Never cuts if `null`. ''; }; }; window = { - alwaysOnTop = - mkEnableOption "forcing the notification window to always be on top"; + alwaysOnTop = mkEnableOption + (lib.mdDoc "forcing the notification window to always be on top"); animation = { easeIn = mkOption { @@ -191,7 +193,8 @@ in { duration = 618; } ''; - description = "Options for the notification appearance's animation."; + description = + lib.mdDoc "Options for the notification appearance's animation."; }; easeOut = mkOption { @@ -204,18 +207,19 @@ in { } ''; description = - "Options for the notification disappearance's animation."; + lib.mdDoc "Options for the notification disappearance's animation."; }; bounce = { - enable = mkEnableOption - "notification bounce when displaying next notification directly"; + enable = mkEnableOption (lib.mdDoc + "notification bounce when displaying next notification directly"); duration = mkOption { type = types.ints.unsigned; default = 500; example = 618; - description = "The bounce animation duration in milliseconds."; + description = + lib.mdDoc "The bounce animation duration in milliseconds."; }; }; }; @@ -224,9 +228,9 @@ in { type = types.str; default = "#000000"; example = "lightgray"; - description = '' + description = lib.mdDoc '' Notification's background color. RGB hex and keywords (e.g. - lightgray) are supported. + `lightgray`) are supported. ''; }; @@ -234,7 +238,7 @@ in { type = types.ints.unsigned; default = 18; example = 42; - description = '' + description = lib.mdDoc '' Height of the slide bar. Useful to match your tiling window manager's bar. ''; @@ -245,7 +249,7 @@ in { type = types.int; default = 0; example = 50; - description = '' + description = lib.mdDoc '' Offset of the notification's slide starting point in pixels on the horizontal axis (positive is rightward). ''; @@ -255,7 +259,7 @@ in { type = types.int; default = 0; example = -100; - description = '' + description = lib.mdDoc '' Offset of the notification's slide starting point in pixels on the vertical axis (positive is upward). ''; @@ -266,7 +270,7 @@ in { type = types.ints.between 0 100; default = 100; example = 80; - description = "The notification window's opacity."; + description = lib.mdDoc "The notification window's opacity."; }; position = mkOption { @@ -288,10 +292,10 @@ in { ]; default = "top_right"; example = "bottom_left"; - description = '' + description = lib.mdDoc '' Position of the notification slide. The notification will slide in vertically from the border if placed in - top_center or bottom_center, + `top_center` or `bottom_center`, horizontally otherwise. ''; }; diff --git a/modules/services/udiskie.nix b/modules/services/udiskie.nix index 19f4eae7..bdb450a7 100644 --- a/modules/services/udiskie.nix +++ b/modules/services/udiskie.nix @@ -48,11 +48,11 @@ in { icon_names.media = [ "media-optical" ]; } ''; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/udiskie/config.yml. - - See + {file}`$XDG_CONFIG_HOME/udiskie/config.yml`. + + See for the full list of options. ''; }; @@ -60,13 +60,13 @@ in { automount = mkOption { type = types.bool; default = true; - description = "Whether to automatically mount new devices."; + description = lib.mdDoc "Whether to automatically mount new devices."; }; notify = mkOption { type = types.bool; default = true; - description = "Whether to show pop-up notifications."; + description = lib.mdDoc "Whether to show pop-up notifications."; }; tray = mkOption { diff --git a/modules/services/unclutter.nix b/modules/services/unclutter.nix index e08c23eb..c8c369f6 100644 --- a/modules/services/unclutter.nix +++ b/modules/services/unclutter.nix @@ -7,29 +7,32 @@ let cfg = config.services.unclutter; in { options.services.unclutter = { - enable = mkEnableOption "unclutter"; + enable = mkEnableOption (lib.mdDoc "unclutter"); package = mkOption { - description = "unclutter derivation to use."; + description = lib.mdDoc "unclutter derivation to use."; type = types.package; default = pkgs.unclutter-xfixes; defaultText = literalExpression "pkgs.unclutter-xfixes"; }; timeout = mkOption { - description = "Number of seconds before the cursor is marked inactive."; + description = + lib.mdDoc "Number of seconds before the cursor is marked inactive."; type = types.int; default = 1; }; threshold = mkOption { - description = "Minimum number of pixels considered cursor movement."; + description = + lib.mdDoc "Minimum number of pixels considered cursor movement."; type = types.int; default = 1; }; extraOptions = mkOption { - description = "More arguments to pass to the unclutter command."; + description = + lib.mdDoc "More arguments to pass to the unclutter command."; type = types.listOf types.str; default = [ ]; example = [ "exclude-root" "ignore-scrolling" ]; diff --git a/modules/services/unison.nix b/modules/services/unison.nix index e32f7052..8c1ba47c 100644 --- a/modules/services/unison.nix +++ b/modules/services/unison.nix @@ -16,7 +16,7 @@ let type = types.path; default = "${config.xdg.dataHome}/unison"; defaultText = "$XDG_DATA_HOME/unison"; - description = '' + description = lib.mdDoc '' Unison state directory to use. ''; }; @@ -32,17 +32,14 @@ let batch = "true"; log = "false"; # don't log to file, handled by systemd }; - description = '' + description = lib.mdDoc '' Additional command line options as a dictionary to pass to the - unison program. - + `unison` program. + Use a list of strings to declare the same option multiple times. - + See - - unison - 1 - + {manpage}`unison(1)` for a list of available options. ''; }; @@ -55,7 +52,7 @@ let "ssh://remote/documents" ] ''; - description = '' + description = lib.mdDoc '' Pair of roots to synchronise. ''; }; @@ -77,7 +74,7 @@ in { meta.maintainers = with maintainers; [ pacien ]; options.services.unison = { - enable = mkEnableOption "Unison synchronisation"; + enable = mkEnableOption (lib.mdDoc "Unison synchronisation"); pairs = mkOption { type = with types; attrsOf (submodule pairOptions); @@ -92,7 +89,7 @@ in { }; } ''; - description = '' + description = lib.mdDoc '' Unison root pairs to keep synchronised. ''; }; diff --git a/modules/services/vdirsyncer.nix b/modules/services/vdirsyncer.nix index ab9230d0..6d325113 100644 --- a/modules/services/vdirsyncer.nix +++ b/modules/services/vdirsyncer.nix @@ -14,26 +14,23 @@ in { meta.maintainers = [ maintainers.pjones ]; options.services.vdirsyncer = { - enable = mkEnableOption "vdirsyncer"; + enable = mkEnableOption (lib.mdDoc "vdirsyncer"); package = mkOption { type = types.package; default = pkgs.vdirsyncer; defaultText = "pkgs.vdirsyncer"; example = literalExpression "pkgs.vdirsyncer"; - description = "The package to use for the vdirsyncer binary."; + description = lib.mdDoc "The package to use for the vdirsyncer binary."; }; frequency = mkOption { type = types.str; default = "*:0/5"; - description = '' + description = lib.mdDoc '' How often to run vdirsyncer. This value is passed to the systemd timer configuration as the onCalendar option. See - - systemd.time - 7 - + {manpage}`systemd.time(7)` for more information about the format. ''; }; @@ -42,7 +39,7 @@ in { type = types.nullOr (types.enum [ "CRITICAL" "ERROR" "WARNING" "INFO" "DEBUG" ]); default = null; - description = '' + description = lib.mdDoc '' Whether vdirsyncer should produce verbose output. ''; }; @@ -50,9 +47,9 @@ in { configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Optional configuration file to link to use instead of - the default file ($XDG_CONFIG_HOME/vdirsyncer/config). + the default file ({file}`$XDG_CONFIG_HOME/vdirsyncer/config`). ''; }; }; diff --git a/modules/services/volnoti.nix b/modules/services/volnoti.nix index 016fe7ab..dfeeca21 100644 --- a/modules/services/volnoti.nix +++ b/modules/services/volnoti.nix @@ -11,14 +11,14 @@ in { options = { services.volnoti = { - enable = mkEnableOption "Volnoti volume HUD daemon"; + enable = mkEnableOption (lib.mdDoc "Volnoti volume HUD daemon"); package = mkOption { type = types.package; default = pkgs.volnoti; defaultText = literalExpression "pkgs.volnoti"; - description = '' - Package containing the volnoti program. + description = lib.mdDoc '' + Package containing the {command}`volnoti` program. ''; }; }; diff --git a/modules/services/window-managers/awesome.nix b/modules/services/window-managers/awesome.nix index d79e72fe..1daa6a68 100644 --- a/modules/services/window-managers/awesome.nix +++ b/modules/services/window-managers/awesome.nix @@ -14,19 +14,19 @@ let in { options = { xsession.windowManager.awesome = { - enable = mkEnableOption "Awesome window manager"; + enable = mkEnableOption (lib.mdDoc "Awesome window manager"); package = mkOption { type = types.package; default = pkgs.awesome; defaultText = literalExpression "pkgs.awesome"; - description = "Package to use for running the Awesome WM."; + description = lib.mdDoc "Package to use for running the Awesome WM."; }; luaModules = mkOption { default = [ ]; type = types.listOf types.package; - description = '' + description = lib.mdDoc '' List of lua packages available for being used in the Awesome configuration. ''; @@ -36,7 +36,7 @@ in { noArgb = mkOption { default = false; type = types.bool; - description = '' + description = lib.mdDoc '' Disable client transparency support, which can be greatly detrimental to performance in some setups ''; diff --git a/modules/services/window-managers/bspwm/options.nix b/modules/services/window-managers/bspwm/options.nix index 848e991b..c23a3346 100644 --- a/modules/services/window-managers/bspwm/options.nix +++ b/modules/services/window-managers/bspwm/options.nix @@ -13,21 +13,21 @@ let monitor = mkOption { type = types.nullOr types.str; default = null; - description = "The monitor where the rule should be applied."; + description = lib.mdDoc "The monitor where the rule should be applied."; example = "HDMI-0"; }; desktop = mkOption { type = types.nullOr types.str; default = null; - description = "The desktop where the rule should be applied."; + description = lib.mdDoc "The desktop where the rule should be applied."; example = "^8"; }; node = mkOption { type = types.nullOr types.str; default = null; - description = "The node where the rule should be applied."; + description = lib.mdDoc "The node where the rule should be applied."; example = "1"; }; @@ -35,28 +35,29 @@ let type = types.nullOr (types.enum [ "tiled" "pseudo_tiled" "floating" "fullscreen" ]); default = null; - description = "The state in which a new window should spawn."; + description = lib.mdDoc "The state in which a new window should spawn."; example = "floating"; }; layer = mkOption { type = types.nullOr (types.enum [ "below" "normal" "above" ]); default = null; - description = "The layer where a new window should spawn."; + description = lib.mdDoc "The layer where a new window should spawn."; example = "above"; }; splitDir = mkOption { type = types.nullOr (types.enum [ "north" "west" "south" "east" ]); default = null; - description = "The direction where the container is going to be split."; + description = + lib.mdDoc "The direction where the container is going to be split."; example = "south"; }; splitRatio = mkOption { type = types.nullOr types.float; default = null; - description = '' + description = lib.mdDoc '' The ratio between the new window and the previous existing window in the desktop. ''; @@ -66,21 +67,22 @@ let hidden = mkOption { type = types.nullOr types.bool; default = null; - description = "Whether the node should occupy any space."; + description = lib.mdDoc "Whether the node should occupy any space."; example = true; }; sticky = mkOption { type = types.nullOr types.bool; default = null; - description = "Whether the node should stay on the focused desktop."; + description = + lib.mdDoc "Whether the node should stay on the focused desktop."; example = true; }; private = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' Whether the node should stay in the same tiling position and size. ''; example = true; @@ -89,8 +91,8 @@ let locked = mkOption { type = types.nullOr types.bool; default = null; - description = '' - Whether the node should ignore node --close + description = lib.mdDoc '' + Whether the node should ignore {command}`node --close` messages. ''; example = true; @@ -99,14 +101,15 @@ let marked = mkOption { type = types.nullOr types.bool; default = null; - description = "Whether the node will be marked for deferred actions."; + description = + lib.mdDoc "Whether the node will be marked for deferred actions."; example = true; }; center = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' Whether the node will be put in the center, in floating mode. ''; example = true; @@ -115,14 +118,15 @@ let follow = mkOption { type = types.nullOr types.bool; default = null; - description = "Whether focus should follow the node when it is moved."; + description = + lib.mdDoc "Whether focus should follow the node when it is moved."; example = true; }; manage = mkOption { type = types.nullOr types.bool; default = null; - description = '' + description = lib.mdDoc '' Whether the window should be managed by bspwm. If false, the window will be ignored by bspwm entirely. This is useful for overlay apps, e.g. screenshot tools. @@ -133,22 +137,22 @@ let focus = mkOption { type = types.nullOr types.bool; default = null; - description = "Whether the node should gain focus on creation."; + description = + lib.mdDoc "Whether the node should gain focus on creation."; example = true; }; border = mkOption { type = types.nullOr types.bool; default = null; - description = "Whether the node should have border."; + description = lib.mdDoc "Whether the node should have border."; example = true; }; rectangle = mkOption { type = types.nullOr types.str; default = null; - description = - "The node's geometry, in the format WxH+X+Y."; + description = lib.mdDoc "The node's geometry, in the format `WxH+X+Y`."; example = "800x600+32+32"; }; }; @@ -156,20 +160,20 @@ let in { xsession.windowManager.bspwm = { - enable = mkEnableOption "bspwm window manager"; + enable = mkEnableOption (lib.mdDoc "bspwm window manager"); package = mkOption { type = types.package; default = pkgs.bspwm; defaultText = literalExpression "pkgs.bspwm"; - description = "The bspwm package to use."; + description = lib.mdDoc "The bspwm package to use."; example = literalExpression "pkgs.bspwm-unstable"; }; settings = mkOption { type = with types; attrsOf (either primitive (listOf primitive)); default = { }; - description = "General settings given to bspc config."; + description = lib.mdDoc "General settings given to `bspc config`."; example = { "border_width" = 2; "split_ratio" = 0.52; @@ -180,7 +184,7 @@ in { extraConfig = mkOption { type = types.lines; default = ""; - description = + description = lib.mdDoc "Additional shell commands to be run at the end of the config file."; example = '' bspc subscribe all > ~/bspc-report.log & @@ -190,7 +194,7 @@ in { extraConfigEarly = mkOption { type = types.lines; default = ""; - description = + description = lib.mdDoc "Like extraConfig, except commands are run at the start of the config file."; }; @@ -198,27 +202,27 @@ in { type = types.attrsOf (types.listOf types.str); default = { }; description = - "Specifies the names of desktops to create on each monitor."; + lib.mdDoc "Specifies the names of desktops to create on each monitor."; example = { "HDMI-0" = [ "web" "terminal" "III" "IV" ]; }; }; alwaysResetDesktops = mkOption { type = types.bool; default = true; - description = '' - If set to true, desktops configured in will be reset + description = lib.mdDoc '' + If set to `true`, desktops configured in {option}`monitors` will be reset every time the config is run. - If set to false, desktops will only be configured the first time the config is run. + If set to `false`, desktops will only be configured the first time the config is run. This is useful if you want to dynamically add desktops and you don't want them to be destroyed if you - re-run bspwmrc. + re-run `bspwmrc`. ''; }; rules = mkOption { type = types.attrsOf rule; default = { }; - description = + description = lib.mdDoc "Rule configuration. The keys of the attribute set are the targets of the rules."; example = literalExpression '' { @@ -240,7 +244,7 @@ in { startupPrograms = mkOption { type = types.listOf types.str; default = [ ]; - description = "Programs to be executed during startup."; + description = lib.mdDoc "Programs to be executed during startup."; example = [ "numlockx on" "tilda" ]; }; }; diff --git a/modules/services/window-managers/fluxbox.nix b/modules/services/window-managers/fluxbox.nix index 3781a020..7b03650d 100644 --- a/modules/services/window-managers/fluxbox.nix +++ b/modules/services/window-managers/fluxbox.nix @@ -11,74 +11,67 @@ in { options = { xsession.windowManager.fluxbox = { - enable = mkEnableOption "Fluxbox window manager"; + enable = mkEnableOption (lib.mdDoc "Fluxbox window manager"); package = mkPackageOptionMD pkgs "fluxbox" { }; init = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Init configuration for Fluxbox, written to - ~/.fluxbox/init. Look at the - - fluxbox - 1 manpage for details. + {file}`~/.fluxbox/init`. Look at the + {manpage}`fluxbox(1)` manpage for details. ''; }; apps = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Apps configuration for Fluxbox, written to - ~/.fluxbox/apps. Look at the - fluxbox - 1 manpage for details. + {file}`~/.fluxbox/apps`. Look at the + {manpage}`fluxbox(1)` manpage for details. ''; }; keys = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Keyboard shortcuts configuration for Fluxbox, written to - ~/.fluxbox/keys. Look at the - fluxbox-keys - 1 manpage for details. + {file}`~/.fluxbox/keys`. Look at the + {manpage}`fluxbox-keys(1)` manpage for details. ''; }; menu = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Menu configuration for Fluxbox, written to - ~/.fluxbox/menu. Look at the - fluxbox-menu - 1 manpage for details. + {file}`~/.fluxbox/menu`. Look at the + {manpage}`fluxbox-menu(1)` manpage for details. ''; }; slitlist = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Slitlist configuration for Fluxbox, written to - ~/.fluxbox/slitlist. Look at the - fluxbox - 1 manpage for details. + {file}`~/.fluxbox/slitlist`. Look at the + {manpage}`fluxbox(1)` manpage for details. ''; }; windowmenu = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Window menu configuration for Fluxbox, written to - ~/.fluxbox/windowmenu. Look at the - fluxbox-menu - 1 + {file}`~/.fluxbox/windowmenu`. Look at the + {manpage}`fluxbox-menu(1)` manpage for details. ''; }; @@ -87,11 +80,10 @@ in { type = with types; listOf str; default = [ ]; example = [ "-log" "/tmp/fluxbox.log" ]; - description = '' - Extra command line arguments to pass to fluxbox. + description = lib.mdDoc '' + Extra command line arguments to pass to {command}`fluxbox`. Look at the - fluxbox - 1 manpage for details. + {manpage}`fluxbox(1)` manpage for details. ''; }; }; diff --git a/modules/services/window-managers/herbstluftwm.nix b/modules/services/window-managers/herbstluftwm.nix index 51fe22bd..be669dce 100644 --- a/modules/services/window-managers/herbstluftwm.nix +++ b/modules/services/window-managers/herbstluftwm.nix @@ -35,15 +35,15 @@ in { meta.maintainers = [ lib.hm.maintainers.olmokramer ]; options.xsession.windowManager.herbstluftwm = { - enable = lib.mkEnableOption "herbstluftwm window manager"; + enable = lib.mkEnableOption (lib.mdDoc "herbstluftwm window manager"); package = lib.mkOption { type = lib.types.package; default = pkgs.herbstluftwm; defaultText = lib.literalExpression "pkgs.herbstluftwm"; - description = '' - Package providing the herbstluftwm and - herbstclient commands. + description = lib.mdDoc '' + Package providing the {command}`herbstluftwm` and + {command}`herbstclient` commands. ''; }; @@ -57,7 +57,7 @@ in { window_border_active_color = "#FF0000"; } ''; - description = "Herbstluftwm settings."; + description = lib.mdDoc "Herbstluftwm settings."; }; keybinds = lib.mkOption { @@ -69,7 +69,7 @@ in { Mod4-u = "split bottom"; } ''; - description = "Herbstluftwm keybinds."; + description = lib.mdDoc "Herbstluftwm keybinds."; }; mousebinds = lib.mkOption { @@ -81,7 +81,7 @@ in { Mod4-B3 = "resize"; } ''; - description = "Herbstluftwm mousebinds."; + description = lib.mdDoc "Herbstluftwm mousebinds."; }; rules = lib.mkOption { @@ -93,7 +93,7 @@ in { "windowtype~'_NET_WM_WINDOW_TYPE_(NOTIFICATION|DOCK|DESKTOP)' manage=off" ] ''; - description = "Herbstluftwm rules."; + description = lib.mdDoc "Herbstluftwm rules."; }; tags = lib.mkOption { @@ -102,7 +102,7 @@ in { example = lib.literalExpression '' [ "work" "browser" "music" "gaming" ] ''; - description = "Tags to create on startup."; + description = lib.mdDoc "Tags to create on startup."; }; extraConfig = lib.mkOption { @@ -112,9 +112,9 @@ in { herbstclient set_layout max herbstclient detect_monitors ''; - description = '' + description = lib.mdDoc '' Extra configuration lines to add verbatim to - $XDG_CONFIG_HOME/herbstluftwm/autostart. + {file}`$XDG_CONFIG_HOME/herbstluftwm/autostart`. ''; }; }; diff --git a/modules/services/window-managers/i3-sway/i3.nix b/modules/services/window-managers/i3-sway/i3.nix index 4f08d4f3..dd5f452e 100644 --- a/modules/services/window-managers/i3-sway/i3.nix +++ b/modules/services/window-managers/i3-sway/i3.nix @@ -91,11 +91,11 @@ let "${cfg.config.modifier}+r" = "mode resize"; }; defaultText = "Default i3 keybindings."; - description = '' + description = lib.mdDoc '' An attribute set that assigns a key press to an action using a key symbol. - See . - - Consider to use lib.mkOptionDefault function to extend or override + See . + + Consider to use `lib.mkOptionDefault` function to extend or override default keybindings instead of specifying all of them from scratch. ''; example = literalExpression '' @@ -121,7 +121,7 @@ let "Return" = "mode default"; }; }; - description = '' + description = lib.mdDoc '' An attribute set that defines binding modes and keybindings inside them @@ -206,21 +206,21 @@ in { options = { xsession.windowManager.i3 = { - enable = mkEnableOption "i3 window manager"; + enable = mkEnableOption (lib.mdDoc "i3 window manager"); package = mkPackageOptionMD pkgs "i3" { }; config = mkOption { type = types.nullOr configModule; default = { }; - description = "i3 configuration options."; + description = lib.mdDoc "i3 configuration options."; }; extraConfig = mkOption { type = types.lines; default = ""; description = - "Extra configuration lines to add to ~/.config/i3/config."; + lib.mdDoc "Extra configuration lines to add to ~/.config/i3/config."; }; }; }; diff --git a/modules/services/window-managers/i3-sway/lib/options.nix b/modules/services/window-managers/i3-sway/lib/options.nix index d669f766..ca4cfa88 100644 --- a/modules/services/window-managers/i3-sway/lib/options.nix +++ b/modules/services/window-managers/i3-sway/lib/options.nix @@ -14,7 +14,7 @@ let type = types.listOf types.str; default = [ "monospace" ]; defaultText = literalExpression ''[ "monospace" ]''; - description = '' + description = lib.mdDoc '' List of font names list used for window titles. Only FreeType fonts are supported. The order here is important (e.g. icons font should go before the one used for text). ''; @@ -24,7 +24,7 @@ let style = mkOption { type = types.str; default = ""; - description = '' + description = lib.mdDoc '' The font style to use for window titles. ''; example = "Bold Semi-Condensed"; @@ -33,7 +33,7 @@ let size = mkOption { type = types.float; default = 8.0; - description = '' + description = lib.mdDoc '' The font size to use for window titles. ''; example = 11.5; @@ -45,31 +45,32 @@ let options = { command = mkOption { type = types.str; - description = "Command that will be executed on startup."; + description = lib.mdDoc "Command that will be executed on startup."; }; always = mkOption { type = types.bool; default = false; - description = "Whether to run command on each ${moduleName} restart."; + description = + lib.mdDoc "Whether to run command on each ${moduleName} restart."; }; } // optionalAttrs isI3 { notification = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable startup-notification support for the command. - See option description in the i3 user guide. + See {option}`--no-startup-id` option description in the i3 user guide. ''; }; workspace = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Launch application on a particular workspace. DEPRECATED: - Use - instead. See . + Use [](#opt-xsession.windowManager.i3.config.assigns) + instead. See . ''; }; }; @@ -99,19 +100,19 @@ let size = 11.0; } ''; - description = "Font configuration for this bar."; + description = lib.mdDoc "Font configuration for this bar."; }; extraConfig = mkOption { type = types.lines; default = ""; - description = "Extra configuration lines for this bar."; + description = lib.mdDoc "Extra configuration lines for this bar."; }; id = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Specifies the bar ID for the configured bar instance. If this option is missing, the ID is set to bar-x, where x corresponds to the position of the embedding bar block in the config file. @@ -121,31 +122,34 @@ let mode = mkNullableOption { type = types.enum [ "dock" "hide" "invisible" ]; default = "dock"; - description = "Bar visibility mode."; + description = lib.mdDoc "Bar visibility mode."; }; hiddenState = mkNullableOption { type = types.enum [ "hide" "show" ]; default = "hide"; - description = "The default bar mode when 'bar.mode' == 'hide'."; + description = + lib.mdDoc "The default bar mode when 'bar.mode' == 'hide'."; }; position = mkNullableOption { type = types.enum [ "top" "bottom" ]; default = "bottom"; - description = "The edge of the screen ${moduleName}bar should show up."; + description = + lib.mdDoc "The edge of the screen ${moduleName}bar should show up."; }; workspaceButtons = mkNullableOption { type = types.bool; default = true; - description = "Whether workspace buttons should be shown or not."; + description = + lib.mdDoc "Whether workspace buttons should be shown or not."; }; workspaceNumbers = mkNullableOption { type = types.bool; default = true; - description = + description = lib.mdDoc "Whether workspace numbers should be displayed within the workspace buttons."; }; @@ -157,7 +161,7 @@ let pkg = if isSway && isNull cfg.package then pkgs.sway else cfg.package; in "${pkg}/bin/${moduleName}bar"; defaultText = "i3bar"; - description = "Command that will be used to start a bar."; + description = lib.mdDoc "Command that will be used to start a bar."; example = if isI3 then "\${pkgs.i3}/bin/i3bar -t" else @@ -167,7 +171,8 @@ let statusCommand = mkNullableOption { type = types.str; default = "${pkgs.i3status}/bin/i3status"; - description = "Command that will be used to get status lines."; + description = + lib.mdDoc "Command that will be used to get status lines."; }; colors = mkOption { @@ -176,25 +181,27 @@ let background = mkNullableOption { type = types.str; default = "#000000"; - description = "Background color of the bar."; + description = lib.mdDoc "Background color of the bar."; }; statusline = mkNullableOption { type = types.str; default = "#ffffff"; - description = "Text color to be used for the statusline."; + description = + lib.mdDoc "Text color to be used for the statusline."; }; separator = mkNullableOption { type = types.str; default = "#666666"; - description = "Text color to be used for the separator."; + description = + lib.mdDoc "Text color to be used for the separator."; }; focusedBackground = mkOption { type = types.nullOr types.str; default = null; - description = + description = lib.mdDoc "Background color of the bar on the currently focused monitor output."; example = "#000000"; }; @@ -202,7 +209,7 @@ let focusedStatusline = mkOption { type = types.nullOr types.str; default = null; - description = + description = lib.mdDoc "Text color to be used for the statusline on the currently focused monitor output."; example = "#ffffff"; }; @@ -210,7 +217,7 @@ let focusedSeparator = mkOption { type = types.nullOr types.str; default = null; - description = + description = lib.mdDoc "Text color to be used for the separator on the currently focused monitor output."; example = "#666666"; }; @@ -222,7 +229,7 @@ let background = "#285577"; text = "#ffffff"; }; - description = '' + description = lib.mdDoc '' Border, background and text color for a workspace button when the workspace has focus. ''; }; @@ -234,7 +241,7 @@ let background = "#5f676a"; text = "#ffffff"; }; - description = '' + description = lib.mdDoc '' Border, background and text color for a workspace button when the workspace is active. ''; }; @@ -246,7 +253,7 @@ let background = "#222222"; text = "#888888"; }; - description = '' + description = lib.mdDoc '' Border, background and text color for a workspace button when the workspace does not have focus and is not active. ''; @@ -259,7 +266,7 @@ let background = "#900000"; text = "#ffffff"; }; - description = '' + description = lib.mdDoc '' Border, background and text color for a workspace button when the workspace contains a window with the urgency hint set. ''; @@ -272,32 +279,32 @@ let background = "#900000"; text = "#ffffff"; }; - description = + description = lib.mdDoc "Border, background and text color for the binding mode indicator"; }; }; }; default = { }; - description = '' + description = lib.mdDoc '' Bar color settings. All color classes can be specified using submodules with 'border', 'background', 'text', fields and RGB color hex-codes as values. See default values for the reference. Note that 'background', 'status', and 'separator' parameters take a single RGB value. - See . + See . ''; }; trayOutput = mkNullableOption { type = types.str; default = "primary"; - description = "Where to output tray."; + description = lib.mdDoc "Where to output tray."; }; trayPadding = mkNullableOption { type = types.int; default = null; - description = '' + description = lib.mdDoc '' Sets the pixel padding of the system tray. This padding will surround the tray on all sides and between each item. ''; @@ -357,16 +364,16 @@ let options = { command = mkOption { type = types.str; - description = "${capitalModuleName}wm command to execute."; + description = lib.mdDoc "${capitalModuleName}wm command to execute."; example = "border pixel 1"; }; criteria = mkOption { type = criteriaModule; - description = '' + description = lib.mdDoc '' Criteria of the windows on which command should be executed. - - A value of true is equivalent to using an empty + + A value of `true` is equivalent to using an empty criteria (which is different from an empty string criteria). ''; example = literalExpression '' @@ -391,7 +398,7 @@ in { size = 11.0; } ''; - description = "Font configuration for window titles, nagbar..."; + description = lib.mdDoc "Font configuration for window titles, nagbar..."; }; window = mkOption { @@ -410,27 +417,28 @@ in { true for state version ≥ 23.05 false for state version < 23.05 ''; - description = "Whether to show window titlebars."; + description = lib.mdDoc "Whether to show window titlebars."; }; border = mkOption { type = types.int; default = 2; - description = "Window border width."; + description = lib.mdDoc "Window border width."; }; hideEdgeBorders = mkOption { type = types.enum [ "none" "vertical" "horizontal" "both" "smart" ]; default = "none"; - description = "Hide window borders adjacent to the screen edges."; + description = + lib.mdDoc "Hide window borders adjacent to the screen edges."; }; commands = mkOption { type = types.listOf windowCommandModule; default = [ ]; - description = '' + description = lib.mdDoc '' List of commands that should be executed on specific windows. - See ${moduleName}wm option documentation. + See {option}`for_window` ${moduleName}wm option documentation. ''; example = [{ command = "border pixel 1"; @@ -440,7 +448,7 @@ in { }; }; default = { }; - description = "Window titlebar and border settings."; + description = lib.mdDoc "Window titlebar and border settings."; }; floating = mkOption { @@ -459,20 +467,20 @@ in { true for state version ≥ 23.05 false for state version < 23.05 ''; - description = "Whether to show floating window titlebars."; + description = lib.mdDoc "Whether to show floating window titlebars."; }; border = mkOption { type = types.int; default = 2; - description = "Floating windows border width."; + description = lib.mdDoc "Floating windows border width."; }; modifier = mkOption { type = types.str; default = cfg.config.modifier; defaultText = "${moduleName}.config.modifier"; - description = + description = lib.mdDoc "Modifier key or keys that can be used to drag floating windows."; example = "Mod4"; }; @@ -480,7 +488,7 @@ in { criteria = mkOption { type = types.listOf criteriaModule; default = [ ]; - description = + description = lib.mdDoc "List of criteria for windows that should be opened in a floating mode."; example = [ { "title" = "Steam - Update News"; } @@ -490,7 +498,7 @@ in { }; }; default = { }; - description = "Floating window settings."; + description = lib.mdDoc "Floating window settings."; }; focus = mkOption { @@ -499,10 +507,10 @@ in { newWindow = mkOption { type = types.enum [ "smart" "urgent" "focus" "none" ]; default = "smart"; - description = '' + description = lib.mdDoc '' This option modifies focus behavior on new window activation. - See + See ''; example = "none"; }; @@ -513,7 +521,7 @@ in { else types.bool; default = if isSway then "yes" else true; - description = "Whether focus should follow the mouse."; + description = lib.mdDoc "Whether focus should follow the mouse."; apply = val: if (isSway && isBool val) then (lib.hm.booleans.yesNo val) else val; }; @@ -526,20 +534,20 @@ in { # so preserve it for backwards compatibility purposes sway = if cfg.config.focus.forceWrapping then "yes" else "no"; }.${moduleName}; - description = '' + description = lib.mdDoc '' Whether the window focus commands automatically wrap around the edge of containers. - See + See ''; }; forceWrapping = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to force focus wrapping in tabbed or stacked containers. - This option is deprecated, use instead. + This option is deprecated, use {option}`focus.wrapping` instead. ''; }; @@ -549,7 +557,7 @@ in { else types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether mouse cursor should be warped to the center of the window when switching focus to a window on a different output. ''; @@ -557,13 +565,13 @@ in { }; }; default = { }; - description = "Focus related settings."; + description = lib.mdDoc "Focus related settings."; }; assigns = mkOption { type = types.attrsOf (types.listOf criteriaModule); default = { }; - description = '' + description = lib.mdDoc '' An attribute set that assigns applications to workspaces based on criteria. ''; @@ -578,7 +586,8 @@ in { modifier = mkOption { type = types.enum [ "Shift" "Control" "Mod1" "Mod2" "Mod3" "Mod4" "Mod5" ]; default = "Mod1"; - description = "Modifier key that is used for all default keybindings."; + description = + lib.mdDoc "Modifier key that is used for all default keybindings."; example = "Mod4"; }; @@ -586,7 +595,7 @@ in { type = types.enum [ "default" "stacking" "tabbed" ]; default = "default"; example = "tabbed"; - description = '' + description = lib.mdDoc '' The mode in which new containers on workspace level will start. ''; @@ -596,7 +605,7 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Assume you are on workspace "1: www" and switch to "2: IM" using mod+2 because somebody sent you a message. You don’t need to remember where you came from now, you can just press $mod+2 again to switch @@ -607,9 +616,9 @@ in { keycodebindings = mkOption { type = types.attrsOf (types.nullOr types.str); default = { }; - description = '' + description = lib.mdDoc '' An attribute set that assigns keypress to an action using key code. - See . + See . ''; example = { "214" = "exec /bin/script.sh"; }; }; @@ -620,7 +629,7 @@ in { background = mkOption { type = types.str; default = "#ffffff"; - description = '' + description = lib.mdDoc '' Background color of the window. Only applications which do not cover the whole area expose the color. ''; @@ -635,7 +644,7 @@ in { indicator = "#2e9ef4"; childBorder = "#285577"; }; - description = "A window which currently has the focus."; + description = lib.mdDoc "A window which currently has the focus."; }; focusedInactive = mkOption { @@ -647,7 +656,7 @@ in { indicator = "#484e50"; childBorder = "#5f676a"; }; - description = '' + description = lib.mdDoc '' A window which is the focused one of its container, but it does not have the focus at the moment. ''; @@ -662,7 +671,7 @@ in { indicator = "#292d2e"; childBorder = "#222222"; }; - description = "A window which is not focused."; + description = lib.mdDoc "A window which is not focused."; }; urgent = mkOption { @@ -674,7 +683,8 @@ in { indicator = "#900000"; childBorder = "#900000"; }; - description = "A window which has its urgency hint activated."; + description = + lib.mdDoc "A window which has its urgency hint activated."; }; placeholder = mkOption { @@ -686,7 +696,7 @@ in { indicator = "#000000"; childBorder = "#0c0c0c"; }; - description = '' + description = lib.mdDoc '' Background and text color are used to draw placeholder window contents (when restoring layouts). Border and indicator are ignored. ''; @@ -694,13 +704,13 @@ in { }; }; default = { }; - description = '' + description = lib.mdDoc '' Color settings. All color classes can be specified using submodules with 'border', 'background', 'text', 'indicator' and 'childBorder' fields and RGB color hex-codes as values. See default values for the reference. Note that '${moduleName}.config.colors.background' parameter takes a single RGB value. - See . + See . ''; }; @@ -751,7 +761,7 @@ in { }] else [ { } ]; defaultText = literalExpression "see code"; - description = '' + description = lib.mdDoc '' ${capitalModuleName} bars settings blocks. Set to empty list to remove bars completely. ''; }; @@ -759,10 +769,10 @@ in { startup = mkOption { type = types.listOf startupModule; default = [ ]; - description = '' + description = lib.mdDoc '' Commands that should be executed at startup. - See . + See . ''; example = if isI3 then literalExpression '' @@ -788,63 +798,63 @@ in { inner = mkOption { type = types.nullOr types.int; default = null; - description = "Inner gaps value."; + description = lib.mdDoc "Inner gaps value."; example = 12; }; outer = mkOption { type = types.nullOr types.int; default = null; - description = "Outer gaps value."; + description = lib.mdDoc "Outer gaps value."; example = 5; }; horizontal = mkOption { type = types.nullOr types.int; default = null; - description = "Horizontal gaps value."; + description = lib.mdDoc "Horizontal gaps value."; example = 5; }; vertical = mkOption { type = types.nullOr types.int; default = null; - description = "Vertical gaps value."; + description = lib.mdDoc "Vertical gaps value."; example = 5; }; top = mkOption { type = types.nullOr types.int; default = null; - description = "Top gaps value."; + description = lib.mdDoc "Top gaps value."; example = 5; }; left = mkOption { type = types.nullOr types.int; default = null; - description = "Left gaps value."; + description = lib.mdDoc "Left gaps value."; example = 5; }; bottom = mkOption { type = types.nullOr types.int; default = null; - description = "Bottom gaps value."; + description = lib.mdDoc "Bottom gaps value."; example = 5; }; right = mkOption { type = types.nullOr types.int; default = null; - description = "Right gaps value."; + description = lib.mdDoc "Right gaps value."; example = 5; }; smartGaps = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' This option controls whether to disable all gaps (outer and inner) on workspace with a single container. ''; @@ -854,7 +864,7 @@ in { smartBorders = mkOption { type = types.enum [ "on" "off" "no_gaps" ]; default = "off"; - description = '' + description = lib.mdDoc '' This option controls whether to disable container borders on workspace with a single container. ''; @@ -862,7 +872,7 @@ in { }; }); default = null; - description = '' + description = lib.mdDoc '' Gaps related settings. ''; }; @@ -870,7 +880,7 @@ in { terminal = mkOption { type = types.str; default = if isI3 then "i3-sensible-terminal" else "${pkgs.foot}/bin/foot"; - description = "Default terminal to run."; + description = lib.mdDoc "Default terminal to run."; example = "alacritty"; }; @@ -880,14 +890,14 @@ in { "${pkgs.dmenu}/bin/dmenu_path | ${pkgs.dmenu}/bin/dmenu | ${pkgs.findutils}/bin/xargs swaymsg exec --" else "${pkgs.dmenu}/bin/dmenu_run"; - description = "Default launcher to use."; + description = lib.mdDoc "Default launcher to use."; example = "bemenu-run"; }; defaultWorkspace = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' The default workspace to show when ${ if isSway then "sway" else "i3" } is launched. @@ -905,7 +915,7 @@ in { type = str; default = ""; example = "Web"; - description = '' + description = lib.mdDoc '' Name of the workspace to assign. ''; }; @@ -915,16 +925,16 @@ in { default = ""; apply = lists.toList; example = "eDP"; - description = '' - Name(s) of the output(s) from + description = lib.mdDoc '' + Name(s) of the output(s) from {command}` ${if isSway then "swaymsg" else "i3-msg"} -t get_outputs - . + `. ''; }; }; }; in listOf workspaceOutputOpts; default = [ ]; - description = "Assign workspaces to outputs."; + description = lib.mdDoc "Assign workspaces to outputs."; }; } diff --git a/modules/services/window-managers/i3-sway/sway.nix b/modules/services/window-managers/i3-sway/sway.nix index 9f412c9c..a37f4419 100644 --- a/modules/services/window-managers/i3-sway/sway.nix +++ b/modules/services/window-managers/i3-sway/sway.nix @@ -22,25 +22,25 @@ let left = mkOption { type = types.str; default = "h"; - description = "Home row direction key for moving left."; + description = lib.mdDoc "Home row direction key for moving left."; }; down = mkOption { type = types.str; default = "j"; - description = "Home row direction key for moving down."; + description = lib.mdDoc "Home row direction key for moving down."; }; up = mkOption { type = types.str; default = "k"; - description = "Home row direction key for moving up."; + description = lib.mdDoc "Home row direction key for moving up."; }; right = mkOption { type = types.str; default = "l"; - description = "Home row direction key for moving right."; + description = lib.mdDoc "Home row direction key for moving right."; }; keybindings = mkOption { @@ -121,11 +121,11 @@ let "${cfg.config.modifier}+r" = "mode resize"; }; defaultText = "Default sway keybindings."; - description = '' + description = lib.mdDoc '' An attribute set that assigns a key press to an action using a key symbol. - See . - - Consider to use lib.mkOptionDefault function to extend or override + See . + + Consider to use `lib.mkOptionDefault` function to extend or override default keybindings instead of specifying all of them from scratch. ''; example = literalExpression '' @@ -143,8 +143,8 @@ let type = types.bool; default = false; example = true; - description = '' - Whether to make use of in keybindings. + description = lib.mdDoc '' + Whether to make use of {option}`--to-code` in keybindings. ''; }; @@ -152,12 +152,9 @@ let type = types.attrsOf (types.attrsOf types.str); default = { }; example = { "*" = { xkb_variant = "dvorak"; }; }; - description = '' + description = lib.mdDoc '' An attribute set that defines input modules. See - - sway-input - 5 - + {manpage}`sway-input(5)` for options. ''; }; @@ -166,12 +163,9 @@ let type = types.attrsOf (types.attrsOf types.str); default = { }; example = { "HDMI-A-2" = { bg = "~/path/to/background.png fill"; }; }; - description = '' + description = lib.mdDoc '' An attribute set that defines output modules. See - - sway-output - 5 - + {manpage}`sway-output(5)` for options. ''; }; @@ -180,12 +174,9 @@ let type = types.attrsOf (types.attrsOf types.str); default = { }; example = { "*" = { hide_cursor = "when-typing enable"; }; }; - description = '' + description = lib.mdDoc '' An attribute set that defines seat modules. See - - sway-input - 5 - + {manpage}`sway-input(5)` for options. ''; }; @@ -206,7 +197,7 @@ let "Return" = "mode default"; }; }; - description = '' + description = lib.mdDoc '' An attribute set that defines binding modes and keybindings inside them @@ -224,7 +215,7 @@ let type = types.bool; inherit default; example = !default; - description = "Whether to make use of the ${description}"; + description = lib.mdDoc "Whether to make use of the ${description}"; }; in { base = mkWrapperFeature true '' @@ -343,16 +334,16 @@ in { ]; options.wayland.windowManager.sway = { - enable = mkEnableOption "sway wayland compositor"; + enable = mkEnableOption (lib.mdDoc "sway wayland compositor"); package = mkOption { type = with types; nullOr package; default = defaultSwayPackage; defaultText = literalExpression "${pkgs.sway}"; - description = '' + description = lib.mdDoc '' Sway package to use. Will override the options 'wrapperFeatures', 'extraSessionCommands', and 'extraOptions'. - Set to null to not add any Sway package to your + Set to `null` to not add any Sway package to your path. This should be done if you want to use the NixOS Sway module to install Sway. ''; @@ -376,19 +367,16 @@ in { ''; }; - xdgAutostart = mkEnableOption '' + xdgAutostart = mkEnableOption (lib.mdDoc '' autostart of applications using - - systemd-xdg-autostart-generator - 8 - - ''; + {manpage}`systemd-xdg-autostart-generator(8)` + ''); }; xwayland = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Enable xwayland, which is needed for the default configuration of sway. ''; }; @@ -397,7 +385,7 @@ in { type = wrapperOptions; default = { }; example = { gtk = true; }; - description = '' + description = lib.mdDoc '' Attribute set of features to enable in the wrapper. ''; }; @@ -414,7 +402,7 @@ in { # use this if they aren't displayed properly: export _JAVA_AWT_WM_NONREPARENTING=1 ''; - description = '' + description = lib.mdDoc '' Shell commands executed just before Sway is started. ''; }; @@ -428,7 +416,7 @@ in { "--unsupported-gpu" "--my-next-gpu-wont-be-nvidia" ]; - description = '' + description = lib.mdDoc '' Command line arguments passed to launch Sway. Please DO NOT report issues if you use an unsupported GPU (proprietary drivers). ''; @@ -437,20 +425,20 @@ in { config = mkOption { type = types.nullOr configModule; default = { }; - description = "Sway configuration options."; + description = lib.mdDoc "Sway configuration options."; }; extraConfig = mkOption { type = types.lines; default = ""; description = - "Extra configuration lines to add to ~/.config/sway/config."; + lib.mdDoc "Extra configuration lines to add to ~/.config/sway/config."; }; extraConfigEarly = mkOption { type = types.lines; default = ""; - description = + description = lib.mdDoc "Like extraConfig, except lines are added to ~/.config/sway/config before all other configuration."; }; }; diff --git a/modules/services/window-managers/i3-sway/swaynag.nix b/modules/services/window-managers/i3-sway/swaynag.nix index 8b77b55f..d8b02723 100644 --- a/modules/services/window-managers/i3-sway/swaynag.nix +++ b/modules/services/window-managers/i3-sway/swaynag.nix @@ -18,23 +18,20 @@ in { options = { wayland.windowManager.sway.swaynag = { - enable = mkEnableOption - "configuration of swaynag, a lightweight error bar for sway"; + enable = mkEnableOption (lib.mdDoc + "configuration of swaynag, a lightweight error bar for sway"); settings = mkOption { type = types.attrsOf confFormat; default = { }; - description = '' + description = lib.mdDoc '' Configuration written to - $XDG_CONFIG_HOME/swaynag/config. - + {file}`$XDG_CONFIG_HOME/swaynag/config`. + See - - swaynag - 5 - + {manpage}`swaynag(5)` for a list of available options and an example configuration. - Note, configurations declared under <config> + Note, configurations declared under `` will override the default type values of swaynag. ''; example = literalExpression '' diff --git a/modules/services/window-managers/spectrwm.nix b/modules/services/window-managers/spectrwm.nix index f2d7af4c..1fd7faba 100644 --- a/modules/services/window-managers/spectrwm.nix +++ b/modules/services/window-managers/spectrwm.nix @@ -30,14 +30,14 @@ in { options = { xsession.windowManager.spectrwm = { - enable = mkEnableOption "Spectrwm window manager"; + enable = mkEnableOption (lib.mdDoc "Spectrwm window manager"); package = mkOption { type = types.package; default = pkgs.spectrwm; defaultText = literalExpression "pkgs.spectrwm"; - description = '' - Package providing the spectrwm command. + description = lib.mdDoc '' + Package providing the {command}`spectrwm` command. ''; }; @@ -52,7 +52,7 @@ in { focus_close = "next"; } ''; - description = "Spectrwm settings."; + description = lib.mdDoc "Spectrwm settings."; }; bindings = mkOption { @@ -65,7 +65,7 @@ in { quit = "Mod+Shift+q"; } ''; - description = "Spectrwm keybindings."; + description = lib.mdDoc "Spectrwm keybindings."; }; unbindings = mkOption { @@ -81,7 +81,7 @@ in { "MOD+t" ] ''; - description = '' + description = lib.mdDoc '' List of keybindings to disable from default Spectrwm configuration. ''; }; @@ -95,7 +95,7 @@ in { search = "dmenu -ip -p 'Window name/id:'; } ''; - description = "Spectrwm programs variables."; + description = lib.mdDoc "Spectrwm programs variables."; }; quirks = mkOption { @@ -107,7 +107,7 @@ in { Pavucontrol = "FLOAT"; } ''; - description = "Spectrwm quicks (custom window rules)."; + description = lib.mdDoc "Spectrwm quicks (custom window rules)."; }; }; }; diff --git a/modules/services/window-managers/xmonad.nix b/modules/services/window-managers/xmonad.nix index 8066bae2..235b885d 100644 --- a/modules/services/window-managers/xmonad.nix +++ b/modules/services/window-managers/xmonad.nix @@ -18,17 +18,17 @@ let in { options = { xsession.windowManager.xmonad = { - enable = mkEnableOption "xmonad window manager"; + enable = mkEnableOption (lib.mdDoc "xmonad window manager"); haskellPackages = mkOption { default = pkgs.haskellPackages; defaultText = literalExpression "pkgs.haskellPackages"; example = literalExpression "pkgs.haskell.packages.ghc784"; - description = '' - The haskellPackages used to build xmonad + description = lib.mdDoc '' + The {var}`haskellPackages` used to build xmonad and other packages. This can be used to change the GHC version used to build xmonad and the packages listed in - extraPackages. + {var}`extraPackages`. ''; }; @@ -41,10 +41,10 @@ in { haskellPackages.monad-logger ] ''; - description = '' + description = lib.mdDoc '' Extra packages available to GHC when rebuilding xmonad. The value must be a function which receives the attribute set - defined in haskellPackages as the sole + defined in {var}`haskellPackages` as the sole argument. ''; }; @@ -52,7 +52,7 @@ in { enableContribAndExtras = mkOption { default = false; type = types.bool; - description = "Enable xmonad-{contrib,extras} in xmonad."; + description = lib.mdDoc "Enable xmonad-{contrib,extras} in xmonad."; }; config = mkOption { @@ -68,16 +68,15 @@ in { } ''' ''; - description = '' + description = lib.mdDoc '' The configuration file to be used for xmonad. This must be - an absolute path or null in which case - ~/.xmonad/xmonad.hs will not be managed + an absolute path or `null` in which case + {file}`~/.xmonad/xmonad.hs` will not be managed by Home Manager. - - - If this option is set to a non-null value, + + If this option is set to a non-`null` value, recompilation of xmonad outside of Home Manager (e.g. via - xmonad --recompile) will fail. + {command}`xmonad --recompile`) will fail. ''; }; @@ -92,9 +91,9 @@ in { '''; } ''; - description = '' + description = lib.mdDoc '' Additional files that will be saved in - ~/.xmonad/lib/ and included in the configuration + {file}`~/.xmonad/lib/` and included in the configuration build. The keys are the file names while the values are paths to the contents of the files. ''; diff --git a/modules/services/wlsunset.nix b/modules/services/wlsunset.nix index 6cd45ed5..8c42dc80 100644 --- a/modules/services/wlsunset.nix +++ b/modules/services/wlsunset.nix @@ -8,30 +8,30 @@ in { meta.maintainers = [ hm.maintainers.matrss ]; options.services.wlsunset = { - enable = mkEnableOption "wlsunset"; + enable = mkEnableOption (lib.mdDoc "wlsunset"); package = mkOption { type = types.package; default = pkgs.wlsunset; defaultText = "pkgs.wlsunset"; - description = '' + description = lib.mdDoc '' wlsunset derivation to use. ''; }; latitude = mkOption { type = types.str; - description = '' - Your current latitude, between -90.0 and - 90.0. + description = lib.mdDoc '' + Your current latitude, between `-90.0` and + `90.0`. ''; }; longitude = mkOption { type = types.str; - description = '' - Your current longitude, between -180.0 and - 180.0. + description = lib.mdDoc '' + Your current longitude, between `-180.0` and + `180.0`. ''; }; @@ -39,18 +39,18 @@ in { day = mkOption { type = types.int; default = 6500; - description = '' + description = lib.mdDoc '' Colour temperature to use during the day, in Kelvin (K). - This value must be greater than temperature.night. + This value must be greater than `temperature.night`. ''; }; night = mkOption { type = types.int; default = 4000; - description = '' + description = lib.mdDoc '' Colour temperature to use during the night, in Kelvin (K). - This value must be smaller than temperature.day. + This value must be smaller than `temperature.day`. ''; }; }; @@ -58,7 +58,7 @@ in { gamma = mkOption { type = types.str; default = "1.0"; - description = '' + description = lib.mdDoc '' Gamma value to use. ''; }; @@ -66,7 +66,7 @@ in { systemdTarget = mkOption { type = types.str; default = "graphical-session.target"; - description = '' + description = lib.mdDoc '' Systemd target to bind to. ''; }; diff --git a/modules/services/xcape.nix b/modules/services/xcape.nix index 72b8303b..dac73f1e 100644 --- a/modules/services/xcape.nix +++ b/modules/services/xcape.nix @@ -11,13 +11,13 @@ in { options = { services.xcape = { - enable = mkEnableOption "xcape"; + enable = mkEnableOption (lib.mdDoc "xcape"); timeout = mkOption { type = types.nullOr types.int; default = null; example = 500; - description = '' + description = lib.mdDoc '' If you hold a key longer than this timeout, xcape will not generate a key event. Default is 500 ms. ''; @@ -30,20 +30,18 @@ in { Shift_L = "Escape"; Control_L = "Control_L|O"; }; - description = '' - The value has the grammar Key[|OtherKey]. - - + description = lib.mdDoc '' + The value has the grammar `Key[|OtherKey]`. + The list of key names is found in the header file - X11/keysymdef.h (remove the - XK_ prefix). Note that due to limitations + {file}`X11/keysymdef.h` (remove the + `XK_` prefix). Note that due to limitations of X11 shifted keys must be specified as a shift key followed by the key to be pressed rather than the actual name of the character. For example to generate "{" the - expression Shift_L|bracketleft could be + expression `Shift_L|bracketleft` could be used (assuming that you have a key with "{" above "["). - - + You can also specify keys in decimal (prefix #), octal (#0), or hexadecimal (#0x). They will be interpreted as keycodes unless no corresponding key name is found. diff --git a/modules/services/xembed-sni-proxy.nix b/modules/services/xembed-sni-proxy.nix index 54ea0599..5a667ee1 100644 --- a/modules/services/xembed-sni-proxy.nix +++ b/modules/services/xembed-sni-proxy.nix @@ -11,14 +11,14 @@ in { options = { services.xembed-sni-proxy = { - enable = mkEnableOption "XEmbed SNI Proxy"; + enable = mkEnableOption (lib.mdDoc "XEmbed SNI Proxy"); package = mkOption { type = types.package; default = pkgs.plasma-workspace; defaultText = literalExpression "pkgs.plasma-workspace"; - description = '' - Package containing the xembedsniproxy + description = lib.mdDoc '' + Package containing the {command}`xembedsniproxy` program. ''; }; diff --git a/modules/services/xidlehook.nix b/modules/services/xidlehook.nix index 9c90fd9f..83bad198 100644 --- a/modules/services/xidlehook.nix +++ b/modules/services/xidlehook.nix @@ -33,13 +33,13 @@ in { meta.maintainers = [ maintainers.dschrempf hm.maintainers.bertof ]; options.services.xidlehook = { - enable = mkEnableOption "xidlehook systemd service"; + enable = mkEnableOption (lib.mdDoc "xidlehook systemd service"); package = mkOption { type = types.package; default = pkgs.xidlehook; defaultText = "pkgs.xidlehook"; - description = "The package to use for xidlehook."; + description = lib.mdDoc "The package to use for xidlehook."; }; environment = mkOption { @@ -50,30 +50,31 @@ in { "primary-display" = "$(xrandr | awk '/ primary/{print $1}')"; } ''; - description = '' + description = lib.mdDoc '' Extra environment variables to be exported in the script. - These options are passed unescaped as export name=value. + These options are passed unescaped as `export name=value`. ''; }; - detect-sleep = mkEnableOption - "detecting when the system wakes up from a suspended state and resetting the idle timer"; + detect-sleep = mkEnableOption (lib.mdDoc + "detecting when the system wakes up from a suspended state and resetting the idle timer"); not-when-fullscreen = mkOption { type = types.bool; default = false; example = true; - description = "Disable locking when a fullscreen application is in use."; + description = + lib.mdDoc "Disable locking when a fullscreen application is in use."; }; not-when-audio = mkOption { type = types.bool; default = false; example = true; - description = "Disable locking when audio is playing."; + description = lib.mdDoc "Disable locking when audio is playing."; }; - once = mkEnableOption "running the program once and exiting"; + once = mkEnableOption (lib.mdDoc "running the program once and exiting"); timers = mkOption { type = types.listOf (types.submodule { @@ -81,14 +82,14 @@ in { delay = mkOption { type = types.ints.unsigned; example = 60; - description = "Time before executing the command."; + description = lib.mdDoc "Time before executing the command."; }; command = mkOption { type = types.nullOr types.str; example = literalExpression '' ''${pkgs.libnotify}/bin/notify-send "Idle" "Sleeping in 1 minute" ''; - description = '' + description = lib.mdDoc '' Command executed after the idle timeout is reached. Path to executables are accepted. The command is automatically escaped. @@ -100,7 +101,7 @@ in { example = literalExpression '' ''${pkgs.libnotify}/bin/notify-send "Idle" "Resuming activity" ''; - description = '' + description = lib.mdDoc '' Command executed when the user becomes active again. This is only executed if the next timer has not been reached. Path to executables are accepted. @@ -125,12 +126,12 @@ in { } ] ''; - description = '' + description = lib.mdDoc '' A set of commands to be executed after a specific idle timeout. - The commands specified in command and canceller + The commands specified in `command` and `canceller` are passed escaped to the script. To use or re-use environment variables that are script-dependent, specify them - in the environment section. + in the `environment` section. ''; }; }; diff --git a/modules/services/xscreensaver.nix b/modules/services/xscreensaver.nix index 3ae92658..569b572f 100644 --- a/modules/services/xscreensaver.nix +++ b/modules/services/xscreensaver.nix @@ -11,7 +11,7 @@ in { options = { services.xscreensaver = { - enable = mkEnableOption "XScreenSaver"; + enable = mkEnableOption (lib.mdDoc "XScreenSaver"); settings = mkOption { type = with types; attrsOf (either bool (either int str)); @@ -21,7 +21,7 @@ in { lock = false; fadeTicks = 20; }; - description = '' + description = lib.mdDoc '' The settings to use for XScreenSaver. ''; }; diff --git a/modules/services/xsettingsd.nix b/modules/services/xsettingsd.nix index 58eb2665..8074a578 100644 --- a/modules/services/xsettingsd.nix +++ b/modules/services/xsettingsd.nix @@ -25,14 +25,14 @@ in { options = { services.xsettingsd = { - enable = mkEnableOption "xsettingsd"; + enable = mkEnableOption (lib.mdDoc "xsettingsd"); package = mkOption { type = types.package; default = pkgs.xsettingsd; defaultText = literalExpression "pkgs.xsettingsd"; - description = '' - Package containing the xsettingsd program. + description = lib.mdDoc '' + Package containing the {command}`xsettingsd` program. ''; }; @@ -47,9 +47,9 @@ in { "Xft/RGBA" = "rgb"; } ''; - description = '' + description = lib.mdDoc '' Xsettingsd options for configuration file. See - + for documentation on these values. ''; }; diff --git a/modules/services/xsuspender.nix b/modules/services/xsuspender.nix index 058f1547..c52ec9e3 100644 --- a/modules/services/xsuspender.nix +++ b/modules/services/xsuspender.nix @@ -11,43 +11,44 @@ let xsuspenderOptions = types.submodule { options = { matchWmClassContains = mkOption { - description = "Match windows that wm class contains string."; + description = lib.mdDoc "Match windows that wm class contains string."; type = types.nullOr types.str; default = null; }; matchWmClassGroupContains = mkOption { - description = "Match windows where wm class group contains string."; + description = + lib.mdDoc "Match windows where wm class group contains string."; type = types.nullOr types.str; default = null; }; matchWmNameContains = mkOption { - description = "Match windows where wm name contains string."; + description = lib.mdDoc "Match windows where wm name contains string."; type = types.nullOr types.str; default = null; }; suspendDelay = mkOption { - description = "Initial suspend delay in seconds."; + description = lib.mdDoc "Initial suspend delay in seconds."; type = types.int; default = 5; }; resumeEvery = mkOption { - description = "Resume interval in seconds."; + description = lib.mdDoc "Resume interval in seconds."; type = types.int; default = 50; }; resumeFor = mkOption { - description = "Resume duration in seconds."; + description = lib.mdDoc "Resume duration in seconds."; type = types.int; default = 5; }; execSuspend = mkOption { - description = '' + description = lib.mdDoc '' Before suspending, execute this shell script. If it fails, abort suspension. ''; @@ -57,7 +58,7 @@ let }; execResume = mkOption { - description = '' + description = lib.mdDoc '' Before resuming, execute this shell script. Resume the process regardless script failure. ''; @@ -67,7 +68,7 @@ let }; sendSignals = mkOption { - description = '' + description = lib.mdDoc '' Whether to send SIGSTOP / SIGCONT signals or not. If false just the exec scripts are run. ''; @@ -77,19 +78,20 @@ let suspendSubtreePattern = mkOption { description = - "Also suspend descendant processes that match this regex."; + lib.mdDoc "Also suspend descendant processes that match this regex."; type = types.nullOr types.str; default = null; }; onlyOnBattery = mkOption { - description = "Whether to enable process suspend only on battery."; + description = + lib.mdDoc "Whether to enable process suspend only on battery."; type = types.bool; default = false; }; autoSuspendOnBattery = mkOption { - description = '' + description = lib.mdDoc '' Whether to auto-apply rules when switching to battery power even if the window(s) didn't just lose focus. ''; @@ -98,7 +100,7 @@ let }; downclockOnBattery = mkOption { - description = '' + description = lib.mdDoc '' Limit CPU consumption for this factor when on battery power. Value 1 means 50% decrease, 2 means 66%, 3 means 75% etc. ''; @@ -113,16 +115,16 @@ in { options = { services.xsuspender = { - enable = mkEnableOption "XSuspender"; + enable = mkEnableOption (lib.mdDoc "XSuspender"); defaults = mkOption { - description = "XSuspender defaults."; + description = lib.mdDoc "XSuspender defaults."; type = xsuspenderOptions; default = { }; }; rules = mkOption { - description = "Attribute set of XSuspender rules."; + description = lib.mdDoc "Attribute set of XSuspender rules."; type = types.attrsOf xsuspenderOptions; default = { }; example = { @@ -135,7 +137,7 @@ in { }; debug = mkOption { - description = "Whether to enable debug output."; + description = lib.mdDoc "Whether to enable debug output."; type = types.bool; default = false; }; diff --git a/modules/systemd.nix b/modules/systemd.nix index 0f8f1018..c83d4dda 100644 --- a/modules/systemd.nix +++ b/modules/systemd.nix @@ -96,8 +96,8 @@ in { default = "${pkgs.systemd}/bin/systemctl"; defaultText = literalExpression ''"''${pkgs.systemd}/bin/systemctl"''; type = types.str; - description = '' - Absolute path to the systemctl tool. This + description = lib.mdDoc '' + Absolute path to the {command}`systemctl` tool. This option may need to be set if running Home Manager on a non-NixOS distribution. ''; @@ -193,7 +193,7 @@ in { servicesStartTimeoutMs = mkOption { default = 0; type = types.ints.unsigned; - description = '' + description = lib.mdDoc '' How long to wait for started services to fail until their start is considered successful. The value 0 indicates no timeout. ''; @@ -203,13 +203,10 @@ in { default = { }; type = with types; attrsOf (either int str); example = { EDITOR = "vim"; }; - description = '' + description = lib.mdDoc '' Environment variables that will be set for the user session. The variable values must be as described in - - environment.d - 5 - . + {manpage}`environment.d(5)`. ''; }; }; diff --git a/modules/targets/darwin/keybindings.nix b/modules/targets/darwin/keybindings.nix index 60582d62..4184300d 100644 --- a/modules/targets/darwin/keybindings.nix +++ b/modules/targets/darwin/keybindings.nix @@ -15,16 +15,16 @@ in { "^u" = "deleteToBeginningOfLine:"; "^w" = "deleteWordBackward:"; }; - description = '' + description = lib.mdDoc '' This will configure the default keybindings for text fields in macOS applications. See - Apple's documentation + [Apple's documentation](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html) for more details. - - Existing keybinding configuration will be wiped when using this - option. - + ::: {.warning} + Existing keybinding configuration will be wiped when using this + option. + ::: ''; }; diff --git a/modules/targets/darwin/search.nix b/modules/targets/darwin/search.nix index 8e0df3b2..75bce8f0 100644 --- a/modules/targets/darwin/search.nix +++ b/modules/targets/darwin/search.nix @@ -16,7 +16,7 @@ in { options.targets.darwin.search = mkOption { type = with types; nullOr (enum (attrNames searchEngines)); default = null; - description = "Default search engine."; + description = lib.mdDoc "Default search engine."; }; config = mkIf (cfg.search != null) { diff --git a/modules/targets/darwin/user-defaults/default.nix b/modules/targets/darwin/user-defaults/default.nix index c397740d..5c420cbc 100644 --- a/modules/targets/darwin/user-defaults/default.nix +++ b/modules/targets/darwin/user-defaults/default.nix @@ -41,18 +41,18 @@ in { DSDontWriteUSBStores = true; }; }; - description = '' - Set macOS user defaults. Values set to null are + description = lib.mdDoc '' + Set macOS user defaults. Values set to `null` are ignored. - - Some settings might require a re-login to take effect. - + ::: {.warning} + Some settings might require a re-login to take effect. + ::: - - Some settings are only read from - . - + ::: {.warning} + Some settings are only read from + {option}`targets.darwin.currentHostDefaults`. + ::: ''; }; @@ -62,16 +62,16 @@ in { example = { "com.apple.controlcenter" = { BatteryShowPercentage = true; }; }; - description = '' - Set macOS user defaults. Unlike , + description = lib.mdDoc '' + Set macOS user defaults. Unlike {option}`targets.darwin.defaults`, the preferences will only be applied to the currently logged-in host. This distinction is important for networked accounts. - Values set to null are ignored. + Values set to `null` are ignored. - - Some settings might require a re-login to take effect. - + ::: {.warning} + Some settings might require a re-login to take effect. + ::: ''; }; diff --git a/modules/targets/darwin/user-defaults/opts-allhosts.nix b/modules/targets/darwin/user-defaults/opts-allhosts.nix index 7f0c5df7..e126494b 100644 --- a/modules/targets/darwin/user-defaults/opts-allhosts.nix +++ b/modules/targets/darwin/user-defaults/opts-allhosts.nix @@ -14,7 +14,7 @@ let type = with types; nullOr bool; default = null; example = true; - description = "Whether to enable ${name}."; + description = lib.mdDoc "Whether to enable ${name}."; }; safari = config."com.apple.Safari"; @@ -26,25 +26,26 @@ in { AppleLanguages = mkNullableOption { type = with types; listOf str; example = [ "en" ]; - description = "Sets the language to use in the preferred order."; + description = + lib.mdDoc "Sets the language to use in the preferred order."; }; AppleLocale = mkNullableOption { type = types.str; example = "en_US"; - description = "Configures the user locale."; + description = lib.mdDoc "Configures the user locale."; }; AppleMeasurementUnits = mkNullableOption { type = types.enum [ "Centimeters" "Inches" ]; example = "Centimeters"; - description = "Sets the measurement unit."; + description = lib.mdDoc "Sets the measurement unit."; }; AppleTemperatureUnit = mkNullableOption { type = types.enum [ "Celsius" "Fahrenheit" ]; example = "Celsius"; - description = "Sets the temperature unit."; + description = lib.mdDoc "Sets the temperature unit."; }; AppleMetricUnits = mkNullableEnableOption "the metric system"; @@ -69,17 +70,17 @@ in { DSDontWriteNetworkStores = mkNullableOption { type = types.bool; example = false; - description = '' - Disable use of .DS_Store files on network shares. - See the - official article for more info. + description = lib.mdDoc '' + Disable use of {file}`.DS_Store` files on network shares. + See [the + official article](https://support.apple.com/en-us/HT208209) for more info. ''; }; DSDontWriteUSBStores = mkNullableOption { type = types.bool; example = false; - description = '' - Disable use of .DS_Store files on thumb drives. + description = lib.mdDoc '' + Disable use of {file}`.DS_Store` files on thumb drives. ''; }; }; @@ -88,7 +89,7 @@ in { tilesize = mkNullableOption { type = types.int; example = 64; - description = "Sets the size of the dock."; + description = lib.mdDoc "Sets the size of the dock."; }; size-immutable = mkNullableEnableOption "locking of the dock size"; expose-group-apps = mkNullableEnableOption @@ -98,9 +99,9 @@ in { "com.apple.menuextra.battery".ShowPercent = mkNullableOption { type = types.enum [ "YES" "NO" ]; example = "NO"; - description = '' + description = lib.mdDoc '' This option no longer works on macOS 11 and later. Instead, use - . + {option}`targets.darwin.currentHostDefaults.\"com.apple.controlcenter\".BatteryShowPercentage`. Whether to show battery percentage in the menu bar. ''; @@ -119,24 +120,24 @@ in { WebKitDeveloperExtrasEnabledPreferenceKey = mkNullableOption { type = types.bool; - description = '' + description = lib.mdDoc '' Configures the web inspector. - - Instead of setting this option directly, set - instead. - + ::: {.warning} + Instead of setting this option directly, set + {option}`IncludeDevelopMenu` instead. + ::: ''; }; "WebKitPreferences.developerExtrasEnabled" = mkNullableOption { type = types.bool; - description = '' + description = lib.mdDoc '' Configures the web inspector. - - Instead of setting this option directly, set - instead. - + ::: {.warning} + Instead of setting this option directly, set + {option}`IncludeDevelopMenu` instead. + ::: ''; }; }; @@ -144,13 +145,13 @@ in { "com.apple.Safari.SandboxBroker" = { ShowDevelopMenu = mkNullableOption { type = types.bool; - description = '' + description = lib.mdDoc '' Show the "Develop" menu in Safari's menubar. - - Instead of setting this option directly, set - instead. - + ::: {.warning} + Instead of setting this option directly, set + {option}`"com.apple.Safari".IncludeDevelopMenu` instead. + ::: ''; }; }; diff --git a/modules/targets/darwin/user-defaults/opts-currenthost.nix b/modules/targets/darwin/user-defaults/opts-currenthost.nix index 129f9148..678f0c0c 100644 --- a/modules/targets/darwin/user-defaults/opts-currenthost.nix +++ b/modules/targets/darwin/user-defaults/opts-currenthost.nix @@ -12,7 +12,7 @@ let type = with lib.types; nullOr bool; default = null; example = true; - description = "Whether to enable ${name}."; + description = lib.mdDoc "Whether to enable ${name}."; }; in { freeformType = with lib.types; attrsOf (attrsOf anything); @@ -21,7 +21,7 @@ in { "com.apple.controlcenter".BatteryShowPercentage = mkNullableOption { type = lib.types.bool; example = true; - description = '' + description = lib.mdDoc '' Whether to show battery percentage in the menu bar. ''; }; diff --git a/modules/xresources.nix b/modules/xresources.nix index 4d9e70c3..5e110465 100644 --- a/modules/xresources.nix +++ b/modules/xresources.nix @@ -43,15 +43,15 @@ in { "XTerm*charClass" = [ "37:48" "45-47:48" "58:48" "64:48" "126:48" ]; } ''; - description = '' + description = lib.mdDoc '' X server resources that should be set. Booleans are formatted as "true" or "false" respectively. List elements are recursively formatted as a string and joined by commas. All other values are directly formatted using builtins.toString. Note, that 2-dimensional lists are not supported and specifying one will throw an exception. If this and all other xresources options are - null, then this feature is disabled and no - ~/.Xresources link is produced. + `null`, then this feature is disabled and no + {file}`~/.Xresources` link is produced. ''; }; @@ -68,11 +68,11 @@ in { } + "/Xresources.dark" ) ''; - description = '' + description = lib.mdDoc '' Additional X server resources contents. If this and all other xresources options are - null, then this feature is disabled and no - ~/.Xresources link is produced. + `null`, then this feature is disabled and no + {file}`~/.Xresources` link is produced. ''; }; @@ -80,8 +80,8 @@ in { type = types.str; default = "${config.home.homeDirectory}/.Xresources"; defaultText = "$HOME/.Xresources"; - description = - "Path where Home Manager should link the .Xresources file."; + description = lib.mdDoc + "Path where Home Manager should link the {file}`.Xresources` file."; }; }; diff --git a/modules/xsession.nix b/modules/xsession.nix index 6d05d432..6ab5f417 100644 --- a/modules/xsession.nix +++ b/modules/xsession.nix @@ -11,14 +11,14 @@ in { options = { xsession = { - enable = mkEnableOption "X Session"; + enable = mkEnableOption (lib.mdDoc "X Session"); scriptPath = mkOption { type = types.str; default = ".xsession"; example = ".xsession-hm"; - description = '' - Path, relative to HOME, where Home Manager + description = lib.mdDoc '' + Path, relative to {env}`HOME`, where Home Manager should write the X session script. ''; }; @@ -27,8 +27,8 @@ in { type = types.str; default = ".xprofile"; example = ".xprofile-hm"; - description = '' - Path, relative to HOME, where Home Manager + description = lib.mdDoc '' + Path, relative to {env}`HOME`, where Home Manager should write the X profile script. ''; }; @@ -44,12 +44,12 @@ in { "''${xmonad}/bin/xmonad"; ''; default = ''test -n "$1" && eval "$@"''; - description = '' + description = lib.mdDoc '' Command to use to start the window manager. - + The default value allows integration with NixOS' generated xserver configuration. - - Extra actions and commands can be specified in . + + Extra actions and commands can be specified in {option}`xsession.initExtra`. ''; }; @@ -57,7 +57,7 @@ in { type = types.bool; default = false; example = true; - description = '' + description = lib.mdDoc '' Whether tray applets should prefer using the Status Notifier Items (SNI) protocol, commonly called App Indicators. Note, not all tray applets or status bars support SNI. @@ -67,13 +67,15 @@ in { profileExtra = mkOption { type = types.lines; default = ""; - description = "Extra shell commands to run before session start."; + description = + lib.mdDoc "Extra shell commands to run before session start."; }; initExtra = mkOption { type = types.lines; default = ""; - description = "Extra shell commands to run during initialization."; + description = + lib.mdDoc "Extra shell commands to run during initialization."; }; importedVariables = mkOption { @@ -81,7 +83,7 @@ in { apply = unique; example = [ "GDK_PIXBUF_ICON_LOADER" ]; visible = false; - description = '' + description = lib.mdDoc '' Environment variables to import into the user systemd session. The will be available for use by graphical services. diff --git a/nixos/common.nix b/nixos/common.nix index 2764e781..0c7663f5 100644 --- a/nixos/common.nix +++ b/nixos/common.nix @@ -81,7 +81,7 @@ in { ''; }; - verbose = mkEnableOption "verbose output on activation"; + verbose = mkEnableOption (lib.mdDoc "verbose output on activation"); users = mkOption { type = types.attrsOf hmModule; diff --git a/tests/asserts.nix b/tests/asserts.nix index c1fe177e..a72f1b9b 100644 --- a/tests/asserts.nix +++ b/tests/asserts.nix @@ -8,13 +8,13 @@ with lib; enable = mkOption { type = types.bool; default = true; - description = "Whether warning asserts are enabled."; + description = lib.mdDoc "Whether warning asserts are enabled."; }; expected = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' List of expected warnings. ''; }; @@ -24,13 +24,13 @@ with lib; enable = mkOption { type = types.bool; default = true; - description = "Whether assertion asserts are enabled."; + description = lib.mdDoc "Whether assertion asserts are enabled."; }; expected = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' List of expected assertions. ''; }; diff --git a/tests/big-test.nix b/tests/big-test.nix index 5396f170..6a93bd07 100644 --- a/tests/big-test.nix +++ b/tests/big-test.nix @@ -4,7 +4,7 @@ options.test.enableBig = lib.mkOption { type = lib.types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to enable "big" tests. These are tests that require more resources than typical tests. For example, tests that depend on large packages or tests that take long to run. diff --git a/tests/stubs.nix b/tests/stubs.nix index 5dee8e43..73d5252d 100644 --- a/tests/stubs.nix +++ b/tests/stubs.nix @@ -9,7 +9,7 @@ let name = mkOption { type = types.str; default = "dummy"; - description = "The stub package name."; + description = lib.mdDoc "The stub package name."; }; outPath = mkOption { @@ -60,7 +60,7 @@ in { type = types.attrsOf stubType; default = { }; description = - "Package attributes that should be replaced by a stub package."; + lib.mdDoc "Package attributes that should be replaced by a stub package."; }; config = {