From 3228f92b9087775869a3cbfb0669a2eb6540452a Mon Sep 17 00:00:00 2001 From: Emily Date: Fri, 30 Jun 2023 23:35:51 +0100 Subject: [PATCH] treewide: manually convert some docs to Markdown These files all have options that trip up the `nix-doc-munge` conversion tool for one reason or another (syntax that clashes with Markdown, options that were already using Markdown syntax despite not being marked that way, output that differs slightly after conversion, syntax too elaborate to convert with some cheap regular expressions, ...). Translate them manually and do a little copyediting to options in the vicinity while we're at it. --- modules/launchd/launchd.nix | 20 ++-- modules/misc/nix.nix | 14 +-- modules/misc/specialisation.nix | 42 ++++---- modules/programs/aerc.nix | 35 ++++--- modules/programs/direnv.nix | 7 +- modules/programs/firefox.nix | 14 ++- modules/programs/himalaya.nix | 12 +-- modules/programs/jq.nix | 7 +- modules/programs/khal.nix | 147 +++++++++++++++------------- modules/programs/pyenv.nix | 13 ++- modules/programs/urxvt.nix | 4 +- modules/programs/vdirsyncer.nix | 7 +- modules/programs/vscode/haskell.nix | 9 +- modules/programs/zsh.nix | 4 +- modules/programs/zsh/prezto.nix | 74 +++++++++----- modules/services/polybar.nix | 24 ++--- nixos/common.nix | 22 ++--- 17 files changed, 242 insertions(+), 213 deletions(-) diff --git a/modules/launchd/launchd.nix b/modules/launchd/launchd.nix index 4ecdad4eb..ead9ce76a 100644 --- a/modules/launchd/launchd.nix +++ b/modules/launchd/launchd.nix @@ -664,27 +664,27 @@ with lib; (types.enum [ "Background" "Standard" "Adaptive" "Interactive" ]); default = null; example = "Background"; - description = '' + description = lib.mdDoc '' This optional key describes, at a high level, the intended purpose of the job. The system will apply resource limits based on what kind of job it is. If left unspecified, the system will apply light resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values: Background - Background jobs are generally processes that do work that was not directly requested by the user. - The resource limits applied to Background jobs are intended to prevent them from disrupting the - user experience. + : Background jobs are generally processes that do work that was not directly requested by the user. + The resource limits applied to Background jobs are intended to prevent them from disrupting the + user experience. Standard - Standard jobs are equivalent to no ProcessType being set. + : Standard jobs are equivalent to no ProcessType being set. Adaptive - Adaptive jobs move between the Background and Interactive classifications based on activity over - XPC connections. See xpc_transaction_begin(3) for details. + : Adaptive jobs move between the Background and Interactive classifications based on activity over + XPC connections. See {manpage}`xpc_transaction_begin(3)` for details. Interactive - Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive - jobs are critical to maintaining a responsive user experience, and this key should only be - used if an app's ability to be responsive depends on it, and cannot be made Adaptive. + : Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive + jobs are critical to maintaining a responsive user experience, and this key should only be + used if an app's ability to be responsive depends on it, and cannot be made Adaptive. ''; }; diff --git a/modules/misc/nix.nix b/modules/misc/nix.nix index e98df2e00..1b5511b4a 100644 --- a/modules/misc/nix.nix +++ b/modules/misc/nix.nix @@ -196,17 +196,11 @@ in { system-features = [ "big-parallel" "kvm" "recursive-nix" ]; } ''; - description = '' - Configuration for Nix, see - or - - nix.conf - 5 - for available options. + description = lib.mdDoc '' + Configuration for Nix; see {manpage}`nix.conf(5)` for available options. The value declared here will be translated directly to the key-value pairs Nix expects. - - - Configuration specified in which will be appended + + Configuration specified in [](#opt-nix.extraOptions) will be appended verbatim to the resulting config file. ''; }; diff --git a/modules/misc/specialisation.nix b/modules/misc/specialisation.nix index e9844f2d2..69c3f617a 100644 --- a/modules/misc/specialisation.nix +++ b/modules/misc/specialisation.nix @@ -34,41 +34,39 @@ with lib; }; }); default = { }; - description = '' + description = lib.mdDoc '' A set of named specialized configurations. These can be used to extend your base configuration with additional settings. For example, you can - have specialisations named light and dark - that applies light and dark color theme configurations. + have specialisations named "light" and "dark" + that apply light and dark color theme configurations. - - - Note, this is an experimental option for now and you therefore have to + ::: {.note} + This is an experimental option for now and you therefore have to activate the specialisation by looking up and running the activation - script yourself. Note, running the activation script will create a new + script yourself. Running the activation script will create a new Home Manager generation. + ::: - - - For example, to activate the dark specialisation. You can + For example, to activate the "dark" specialisation, you can first look up your current Home Manager generation by running - - $ home-manager generations | head -1 - 2022-05-02 22:49 : id 1758 -> /nix/store/jy…ac-home-manager-generation - + ```console + $ home-manager generations | head -1 + 2022-05-02 22:49 : id 1758 -> /nix/store/jy…ac-home-manager-generation + ``` then run - - $ /nix/store/jy…ac-home-manager-generation/specialisation/dark/activate - Starting Home Manager activation - … - + ```console + $ /nix/store/jy…ac-home-manager-generation/specialisation/dark/activate + Starting Home Manager activation + … + ``` - - - WARNING! Since this option is experimental, the activation process may + ::: {.warning} + Since this option is experimental, the activation process may change in backwards incompatible ways. + ::: ''; }; diff --git a/modules/programs/aerc.nix b/modules/programs/aerc.nix index ccd26e211..78f5bd661 100644 --- a/modules/programs/aerc.nix +++ b/modules/programs/aerc.nix @@ -40,9 +40,10 @@ in { default = { }; example = literalExpression ''{ Work = { source = "maildir://~/Maildir/work"; }; }''; - description = '' - Extra lines added to $HOME/.config/aerc/accounts.conf. - See aerc-config(5). + description = lib.mdDoc '' + Extra lines added to {file}`$HOME/.config/aerc/accounts.conf`. + + See {manpage}`aerc-config(5)`. ''; }; @@ -50,10 +51,11 @@ in { type = sectionsOrLines; default = { }; example = literalExpression ''{ messages = { q = ":quit"; }; }''; - description = '' - Extra lines added to $HOME/.config/aerc/binds.conf. + description = lib.mdDoc '' + Extra lines added to {file}`$HOME/.config/aerc/binds.conf`. Global keybindings can be set in the `global` section. - See aerc-config(5). + + See {manpage}`aerc-config(5)`. ''; }; @@ -61,9 +63,10 @@ in { type = sectionsOrLines; default = { }; example = literalExpression ''{ ui = { sort = "-r date"; }; }''; - description = '' - Extra lines added to $HOME/.config/aerc/aerc.conf. - See aerc-config(5). + description = lib.mdDoc '' + Extra lines added to {file}`$HOME/.config/aerc/aerc.conf`. + + See {manpage}`aerc-config(5)`. ''; }; @@ -73,9 +76,10 @@ in { example = literalExpression '' { default = { ui = { "tab.selected.reverse" = toggle; }; }; }; ''; - description = '' - Stylesets added to $HOME/.config/aerc/stylesets/. - See aerc-stylesets(7). + description = lib.mdDoc '' + Stylesets added to {file}`$HOME/.config/aerc/stylesets/`. + + See {manpage}`aerc-stylesets(7)`. ''; }; @@ -85,9 +89,10 @@ in { example = literalExpression '' { new_message = "Hello!"; }; ''; - description = '' - Templates added to $HOME/.config/aerc/templates/. - See aerc-templates(7). + description = lib.mdDoc '' + Templates added to {file}`$HOME/.config/aerc/templates/`. + + See {manpage}`aerc-templates(7)`. ''; }; }; diff --git a/modules/programs/direnv.nix b/modules/programs/direnv.nix index 676a762d3..2e89695f7 100644 --- a/modules/programs/direnv.nix +++ b/modules/programs/direnv.nix @@ -89,10 +89,9 @@ in { }; nix-direnv = { - enable = mkEnableOption '' - nix-direnv, - a fast, persistent use_nix implementation for direnv''; + enable = mkEnableOption (lib.mdDoc '' + [nix-direnv](https://github.com/nix-community/nix-direnv), + a fast, persistent use_nix implementation for direnv''); }; }; diff --git a/modules/programs/firefox.nix b/modules/programs/firefox.nix index 91ce2c308..b9d9d2f87 100644 --- a/modules/programs/firefox.nix +++ b/modules/programs/firefox.nix @@ -442,20 +442,18 @@ in { privacy-badger ] ''; - description = '' + description = lib.mdDoc '' List of Firefox add-on packages to install for this profile. - Some pre-packaged add-ons are accessible from NUR, - . + Some pre-packaged add-ons are accessible from the + [Nix User Repository](https://github.com/nix-community/NUR). Once you have NUR installed run - - $ nix-env -f '<nixpkgs>' -qaP -A nur.repos.rycee.firefox-addons - + ```console + $ nix-env -f '' -qaP -A nur.repos.rycee.firefox-addons + ``` to list the available Firefox add-ons. - - Note that it is necessary to manually enable these extensions inside Firefox after the first installation. ''; diff --git a/modules/programs/himalaya.nix b/modules/programs/himalaya.nix index e075c3262..0761c9bb8 100644 --- a/modules/programs/himalaya.nix +++ b/modules/programs/himalaya.nix @@ -218,18 +218,18 @@ in { backend = lib.mkOption { type = with lib.types; nullOr str; default = null; - description = '' - Specifying 'accounts.email.accounts.*.himalaya.backend' is deprecated, - set 'accounts.email.accounts.*.himalaya.settings.backend' instead. + description = lib.mdDoc '' + Specifying {option}`accounts.email.accounts.*.himalaya.backend` is deprecated, + set {option}`accounts.email.accounts.*.himalaya.settings.backend` instead. ''; }; # TODO: remove me for the next release sender = lib.mkOption { type = with lib.types; nullOr str; - description = '' - Specifying 'accounts.email.accounts.*.himalaya.sender' is deprecated, - set 'accounts.email.accounts.*.himalaya.settings.sender' instead. + description = lib.mdDoc '' + Specifying {option}`accounts.email.accounts.*.himalaya.sender` is deprecated, + set {option}'accounts.email.accounts.*.himalaya.settings.sender' instead. ''; }; diff --git a/modules/programs/jq.nix b/modules/programs/jq.nix index e810f8845..78ad57f59 100644 --- a/modules/programs/jq.nix +++ b/modules/programs/jq.nix @@ -38,10 +38,11 @@ in { }; colors = mkOption { - description = '' - The colors used in colored JSON output. + description = lib.mdDoc '' + The colors used in colored JSON output. - See . + See the [Colors section](https://jqlang.github.io/jq/manual/#Colors) + of the jq manual. ''; example = literalExpression '' diff --git a/modules/programs/khal.nix b/modules/programs/khal.nix index 209716a17..57467c89d 100644 --- a/modules/programs/khal.nix +++ b/modules/programs/khal.nix @@ -33,116 +33,123 @@ let (toKeyValueIfDefined (getAttrs [ "type" "color" "priority" ] value.khal)) ] ++ [ "\n" ]); - localeFormatOptions = let T = lib.types; - in mapAttrs (n: v: - v // { - description = v.description + '' + localeFormatOptions = let + T = lib.types; + suffix = '' + Format strings are for Python `strftime`, similarly to + {manpage}`strftime(3)`. + ''; + in { + dateformat = mkOption { + type = T.str; + default = "%x"; + description = lib.mdDoc '' + khal will display and understand all dates in this format. - Format strings are for python 'strftime', similarly to man 3 strftime. + ${suffix} ''; - }) { - dateformat = { - type = T.str; - default = "%x"; - description = '' - khal will display and understand all dates in this format. - ''; - }; - - timeformat = { - type = T.str; - default = "%X"; - description = '' - khal will display and understand all times in this format. - ''; - }; - - datetimeformat = { - type = T.str; - default = "%c"; - description = '' - khal will display and understand all datetimes in this format. - ''; - }; - - longdateformat = { - type = T.str; - default = "%x"; - description = '' - khal will display and understand all dates in this format. - It should contain a year (e.g. %Y). - ''; - }; - - longdatetimeformat = { - type = T.str; - default = "%c"; - description = '' - khal will display and understand all datetimes in this format. - It should contain a year (e.g. %Y). - ''; - }; }; + timeformat = mkOption { + type = T.str; + default = "%X"; + description = lib.mdDoc '' + khal will display and understand all times in this format. + + ${suffix} + ''; + }; + + datetimeformat = mkOption { + type = T.str; + default = "%c"; + description = lib.mdDoc '' + khal will display and understand all datetimes in this format. + + ${suffix} + ''; + }; + + longdateformat = mkOption { + type = T.str; + default = "%x"; + description = lib.mdDoc '' + khal will display and understand all dates in this format. + It should contain a year (e.g. `%Y`). + + ${suffix} + ''; + }; + + longdatetimeformat = mkOption { + type = T.str; + default = "%c"; + description = lib.mdDoc '' + khal will display and understand all datetimes in this format. + It should contain a year (e.g. `%Y`). + + ${suffix} + ''; + }; + }; + localeOptions = let T = lib.types; in localeFormatOptions // { - unicode_symbols = { + unicode_symbols = mkOption { type = T.bool; default = true; - description = '' - By default khal uses some unicode symbols (as in ‘non-ascii’) as + description = lib.mdDoc '' + By default khal uses some Unicode symbols (as in "non-ASCII") as indicators for things like repeating events. If your font, encoding etc. does not support those symbols, set this - to false (this will enable ascii based replacements). + to false (this will enable ASCII-based replacements). ''; }; - default_timezone = { + default_timezone = mkOption { type = T.nullOr T.str; default = null; - description = '' + description = lib.mdDoc '' Default for new events or if khal does not understand the timezone in an ical file. - If 'null', the timezone of your computer will be used. + If `null`, the timezone of your computer will be used. ''; }; - local_timezone = { + local_timezone = mkOption { type = T.nullOr T.str; default = null; - description = '' + description = lib.mdDoc '' khal will show all times in this timezone. - If 'null', the timezone of your computer will be used. + If `null`, the timezone of your computer will be used. ''; }; - firstweekday = { + firstweekday = mkOption { type = T.ints.between 0 6; default = 0; - description = '' - the first day of the week, where Monday is 0 and Sunday is 6 + description = lib.mdDoc '' + The first day of the week, where Monday is 0 and Sunday is 6. ''; }; - weeknumbers = { + weeknumbers = mkOption { type = T.enum [ "off" "left" "right" ]; default = "off"; - description = '' - Enable weeknumbers in calendar and interactive (ikhal) mode. - As those are iso weeknumbers, they only work properly if firstweekday - is set to 0. + description = lib.mdDoc '' + Enable week numbers in calendar and interactive (ikhal) mode. + As those are ISO week numbers, they only work properly if + {option}`firstweekday` is set to 0. ''; }; }; in { options.programs.khal = { - enable = mkEnableOption "khal, a CLI calendar application"; + enable = mkEnableOption (lib.mdDoc "khal, a CLI calendar application"); locale = mkOption { - type = lib.types.submodule { - options = mapAttrs (n: v: mkOption v) localeOptions; - }; - description = '' + type = lib.types.submodule { options = localeOptions; }; + description = lib.mdDoc '' khal locale settings. ''; }; diff --git a/modules/programs/pyenv.nix b/modules/programs/pyenv.nix index a83713bbf..5ff0a83a4 100644 --- a/modules/programs/pyenv.nix +++ b/modules/programs/pyenv.nix @@ -48,11 +48,14 @@ in { apply = toString; default = "${config.xdg.dataHome}/pyenv"; defaultText = "\${config.xdg.dataHome}/pyenv"; - description = '' - The pyenv root directory (PYENV_ROOT). - - Note: Deviating from upstream which uses `$HOME/.pyenv`, - the default path is set according to the XDG base directory specification. + description = lib.mdDoc '' + The pyenv root directory ({env}`PYENV_ROOT`). + + ::: {.note} + This deviates from upstream, which uses {file}`$HOME/.pyenv`. + The default path in Home Manager is set according to the XDG + base directory specification. + ::: ''; }; }; diff --git a/modules/programs/urxvt.nix b/modules/programs/urxvt.nix index 545a1e7f8..1619ba076 100644 --- a/modules/programs/urxvt.nix +++ b/modules/programs/urxvt.nix @@ -118,8 +118,8 @@ in { shading = mkOption { type = types.ints.between 0 200; default = 100; - description = - "Darken (0 .. 99) or lighten (101 .. 200) the transparent background."; + description = lib.mdDoc + "Darken (0 to 99) or lighten (101 to 200) the transparent background."; }; extraConfig = mkOption { diff --git a/modules/programs/vdirsyncer.nix b/modules/programs/vdirsyncer.nix index 258692df1..91671c182 100644 --- a/modules/programs/vdirsyncer.nix +++ b/modules/programs/vdirsyncer.nix @@ -182,12 +182,11 @@ in { type = types.str; default = "${config.xdg.dataHome}/vdirsyncer/status"; defaultText = "$XDG_DATA_HOME/vdirsyncer/status"; - description = '' + description = lib.mdDoc '' A directory where vdirsyncer will store some additional data for the next sync. - - For more information, see - + For more information, see the + [vdirsyncer manual](https://vdirsyncer.pimutils.org/en/stable/config.html#general-section). ''; }; }; diff --git a/modules/programs/vscode/haskell.nix b/modules/programs/vscode/haskell.nix index 7fe3235d8..4867d0a7c 100644 --- a/modules/programs/vscode/haskell.nix +++ b/modules/programs/vscode/haskell.nix @@ -35,12 +35,15 @@ in { type = types.path; default = defaultHieNixExe; defaultText = defaultHieNixExeText; - description = '' + description = lib.mdDoc '' The path to the Haskell IDE Engine executable. - + Because hie-nix is not packaged in Nixpkgs, you need to add it as an overlay or set this option. Example overlay configuration: - ${exampleOverlay} + + ```nix + ${exampleOverlay} + ``` ''; example = literalExpression '' (import ~/src/haskell-ide-engine {}).hies + "/bin/hie-wrapper"; diff --git a/modules/programs/zsh.nix b/modules/programs/zsh.nix index d69ea7c32..221a57601 100644 --- a/modules/programs/zsh.nix +++ b/modules/programs/zsh.nix @@ -248,8 +248,8 @@ in cdpath = mkOption { default = []; - description = '' - List of paths to autocomplete calls to `cd`. + description = lib.mdDoc '' + List of paths to autocomplete calls to {command}`cd`. ''; type = types.listOf types.str; }; diff --git a/modules/programs/zsh/prezto.nix b/modules/programs/zsh/prezto.nix index 5aaf205f3..5673c28f6 100644 --- a/modules/programs/zsh/prezto.nix +++ b/modules/programs/zsh/prezto.nix @@ -26,14 +26,16 @@ let type = types.nullOr types.bool; default = true; example = false; - description = "Color output (auto set to 'no' on dumb terminals)"; + description = lib.mdDoc '' + Color output (automatically set to `false` on dumb terminals). + ''; }; pmoduleDirs = mkOption { type = types.listOf types.path; default = [ ]; example = [ "$HOME/.zprezto-contrib" ]; - description = "Add additional directories to load prezto modules from"; + description = "Add additional directories to load prezto modules from."; }; extraConfig = mkOption { @@ -48,14 +50,18 @@ let type = types.listOf types.str; default = [ ]; example = [ "attr" "stat" ]; - description = "Set the Zsh modules to load (man zshmodules)."; + description = lib.mdDoc '' + Set the Zsh modules to load ({manpage}`zshmodules(1)`). + ''; }; extraFunctions = mkOption { type = types.listOf types.str; default = [ ]; example = [ "zargs" "zmv" ]; - description = "Set the Zsh functions to load (man zshcontrib)."; + description = lib.mdDoc '' + Set the Zsh functions to load ({manpage}`zshcontrib(1)`). + ''; }; pmodules = mkOption { @@ -86,8 +92,10 @@ let type = types.listOf types.str; default = [ ]; example = [ "0.0.0.0" "127.0.0.1" ]; - description = - "Set the entries to ignore in static */etc/hosts* for host completion."; + description = lib.mdDoc '' + Set the entries to ignore in static {file}`/etc/hosts` for + host completion. + ''; }; editor = { @@ -95,21 +103,25 @@ let type = types.nullOr (types.enum [ "emacs" "vi" ]); default = "emacs"; example = "vi"; - description = "Set the key mapping style to 'emacs' or 'vi'."; + description = lib.mdDoc '' + Set the key mapping style to `emacs` or `vi`. + ''; }; dotExpansion = mkOption { type = types.nullOr types.bool; default = null; example = true; - description = "Auto convert .... to ../.."; + description = lib.mdDoc '' + Automatically convert `....` to `../..` + ''; }; promptContext = mkOption { type = types.nullOr types.bool; default = null; example = true; - description = "Allow the zsh prompt context to be shown."; + description = "Allow the Zsh prompt context to be shown."; }; }; @@ -117,8 +129,10 @@ let type = types.nullOr (types.enum [ "dirty" "untracked" "all" "none" ]); default = null; example = "all"; - description = - "Ignore submodules when they are 'dirty', 'untracked', 'all', or 'none'."; + description = lib.mdDoc '' + Ignore submodules when they are `dirty`, `untracked`, `all`, + or `none`. + ''; }; gnuUtility.prefix = mkOption { @@ -154,8 +168,10 @@ let type = types.nullOr types.str; default = null; example = "manpages"; - description = - "Set the keyword used by `mand` to open man pages in Dash.app"; + description = lib.mdDoc '' + Set the keyword used by {command}`mand` to open man pages + in Dash.app. + ''; }; prompt = { @@ -163,19 +179,23 @@ let type = types.nullOr types.str; default = "sorin"; example = "pure"; - description = '' - Set the prompt theme to load. Setting it to 'random' - loads a random theme. Auto set to 'off' on dumb terminals.''; + description = lib.mdDoc '' + Set the prompt theme to load. Setting it to `random` + loads a random theme. Automatically set to `off` on dumb + terminals. + ''; }; pwdLength = mkOption { type = types.nullOr (types.enum [ "short" "long" "full" ]); default = null; example = "short"; - description = '' + description = lib.mdDoc '' Set the working directory prompt display length. By - default, it is set to 'short'. Set it to 'long' (without '~' expansion) for - longer or 'full' (with '~' expansion) for even longer prompt display.''; + default, it is set to `short`. Set it to `long` (without `~` + expansion) for longer or `full` (with `~` expansion) for + even longer prompt display. + ''; }; showReturnVal = mkOption { @@ -184,7 +204,8 @@ let example = true; description = '' Set the prompt to display the return code along with an - indicator for non-zero return codes. This is not supported by all prompts.''; + indicator for non-zero return codes. This is not supported by all prompts. + ''; }; }; @@ -244,7 +265,8 @@ let example = [ "main" "brackets" "pattern" "line" "cursor" "root" ]; description = '' Set syntax highlighters. By default, only the main - highlighter is enabled.''; + highlighter is enabled. + ''; }; styles = mkOption { @@ -332,10 +354,12 @@ let type = types.nullOr types.bool; default = null; example = true; - description = '' - Enabled safe options. This aliases cp, ln, mv and rm so - that they prompt before deleting or overwriting files. Set to 'no' to disable - this safer behavior.''; + description = lib.mdDoc '' + Enabled safe options. This aliases {command}`cp`, + {command}`ln`, {command}`mv` and {command}`rm` so that they + prompt before deleting or overwriting files. Set to `no` to + disable this safer behavior. + ''; }; }; }; diff --git a/modules/services/polybar.nix b/modules/services/polybar.nix index d3ac68ded..d008c580e 100644 --- a/modules/services/polybar.nix +++ b/modules/services/polybar.nix @@ -122,38 +122,38 @@ in { type = with types; let ty = oneOf [ bool int float str (listOf ty) (attrsOf ty) ]; in attrsOf (attrsOf ty // { description = "attribute sets"; }); - description = '' + description = lib.mdDoc '' Polybar configuration. This takes a nix attrset and converts it to the strange data format that polybar uses. Each entry will be converted to a section in the output file. Several things are treated specially: nested keys are converted - to dash-separated keys; the special text key is ignored as a nested key, + to dash-separated keys; the special `text` key is ignored as a nested key, to allow mixing different levels of nesting; and lists are converted to - polybar's foo-0, foo-1, ... format. - + polybar's `foo-0, foo-1, ...` format. + For example: - + ```nix "module/volume" = { type = "internal/pulseaudio"; - format.volume = "<ramp-volume> <label-volume>"; + format.volume = " "; label.muted.text = "🔇"; label.muted.foreground = "#666"; ramp.volume = ["🔈" "🔉" "🔊"]; - click.right = "pavucontrol &"; + click.right = "pavucontrol &"; } - + ``` becomes: - + ```ini [module/volume] type=internal/pulseaudio - format-volume=<ramp-volume> <label-volume> + format-volume= label-muted=🔇 label-muted-foreground=#666 ramp-volume-0=🔈 ramp-volume-1=🔉 ramp-volume-2=🔊 - click-right=pavucontrol & - + click-right=pavucontrol & + ``` ''; default = { }; example = literalExpression '' diff --git a/nixos/common.nix b/nixos/common.nix index a897799d9..2764e7812 100644 --- a/nixos/common.nix +++ b/nixos/common.nix @@ -43,22 +43,20 @@ let in { options.home-manager = { - useUserPackages = mkEnableOption '' + useUserPackages = mkEnableOption (mdDoc '' installation of user packages through the - option - ''; + {option}`users.users..packages` option''); - useGlobalPkgs = mkEnableOption '' - using the system configuration's pkgs + useGlobalPkgs = mkEnableOption (mdDoc '' + using the system configuration's `pkgs` argument in Home Manager. This disables the Home Manager - options - ''; + options {option}`nixpkgs.*`''); backupFileExtension = mkOption { type = types.nullOr types.str; default = null; example = "backup"; - description = '' + description = mdDoc '' On activation move existing files by appending the given file extension rather than exiting with an error. ''; @@ -68,8 +66,8 @@ in { type = types.attrs; default = { }; example = literalExpression "{ inherit emacs-overlay; }"; - description = '' - Extra specialArgs passed to Home Manager. This + description = mdDoc '' + Extra `specialArgs` passed to Home Manager. This option can be used to pass additional arguments to all modules. ''; }; @@ -78,7 +76,7 @@ in { type = with types; listOf raw; default = [ ]; example = literalExpression "[ { home.packages = [ nixpkgs-fmt ]; } ]"; - description = '' + description = mdDoc '' Extra modules added to all users. ''; }; @@ -90,7 +88,7 @@ in { default = { }; # Prevent the entire submodule being included in the documentation. visible = "shallow"; - description = '' + description = mdDoc '' Per-user Home Manager configuration. ''; };