From b97c235e37c91511c2e7533ab6794480e4cc445a Mon Sep 17 00:00:00 2001 From: Emily Date: Thu, 22 Jun 2023 02:34:49 +0100 Subject: treewide: tweak DocBook docs for conversion These help `nix-munge-doc` automate more of the Markdown conversion process. See the following nixpkgs commits for explanations of many of these changes: * https://github.com/NixOS/nixpkgs/commit/275a34e0d8a937a81b267e47302dd8a92fa781df * https://github.com/NixOS/nixpkgs/commit/694d5b19d30bf66687b42fb77f43ea7cd1002a62 * https://github.com/NixOS/nixpkgs/commit/f1d39b6d6187997b630647400c5efe5b01e06a23 * https://github.com/NixOS/nixpkgs/commit/16102dce2fbad670bd47dd75c860a8daa5fe47ad I couldn't think of any particularly good way to format the `system.defaults` breadcrumbs, so I just made them standalone paragraphs. They weren't rendering correctly in DocBook anyway. --- modules/homebrew.nix | 75 ++++++++++++++---------------- modules/nix/default.nix | 9 ++-- modules/services/postgresql/default.nix | 8 ++-- modules/services/synergy/default.nix | 4 +- modules/system/defaults/NSGlobalDomain.nix | 12 +++-- modules/system/defaults/alf.nix | 15 ++++-- modules/system/defaults/loginwindow.nix | 27 +++++++---- modules/system/defaults/spaces.nix | 3 +- modules/system/patches.nix | 6 +-- 9 files changed, 87 insertions(+), 72 deletions(-) (limited to 'modules') diff --git a/modules/homebrew.nix b/modules/homebrew.nix index 200e0d7..63f1450 100644 --- a/modules/homebrew.nix +++ b/modules/homebrew.nix @@ -31,9 +31,6 @@ let # Option and submodule helper functions ---------------------------------------------------------- - mkDocOptionLink = optionName: - ''''; - mkNullOrBoolOption = args: mkOption (args // { type = types.nullOr types.bool; default = null; @@ -104,7 +101,7 @@ let Although auto-updating is disabled by default during system activation, note that Homebrew will auto-update when you manually invoke certain Homebrew commands. To modify this - behavior see ${mkDocOptionLink "homebrew.global.autoUpdate"}. + behavior see . ''; }; upgrade = mkOption { @@ -141,7 +138,7 @@ let the Nix store, when you manually invoke brew bundle. Enabling this option will change the default value of - ${mkDocOptionLink "homebrew.global.lockfiles"} to false since, with + to false since, with this option enabled, brew bundle [install] will default to using the Brewfile that this module generates in the Nix store, unless you explicitly point it at another Brewfile using the --file flag. As a result, it will try to @@ -151,7 +148,7 @@ let Implementation note: when enabled, this option sets the HOMEBREW_BUNDLE_FILE environment variable to the path of the Brewfile that this module generates in the Nix store, by adding it to - ${mkDocOptionLink "environment.variables"}. + . ''; }; autoUpdate = mkOption { @@ -166,14 +163,14 @@ let above if it's been more then 5 minutes since it last updated. You may want to consider disabling this option if you have - ${mkDocOptionLink "homebrew.onActivation.upgrade"} enabled, and - ${mkDocOptionLink "homebrew.onActivation.autoUpdate"} disabled, if you want to ensure that + enabled, and + disabled, if you want to ensure that your installed formulae will only be upgraded during nix-darwin system activation, after you've explicitly run brew update. Implementation note: when disabled, this option sets the HOMEBREW_NO_AUTO_UPDATE environment variable, by adding it to - ${mkDocOptionLink "environment.variables"}. + . ''; }; lockfiles = mkOption { @@ -185,7 +182,7 @@ let brew bundle [install]. This option will default to false if - ${mkDocOptionLink "homebrew.global.brewfile"} is enabled since, with that option enabled, + is enabled since, with that option enabled, brew bundle [install] will default to using the Brewfile that this module generates in the Nix store, unless you explicitly point it at another Brewfile using the --file flag. As a result, it will try to write the @@ -194,7 +191,7 @@ let Implementation note: when disabled, this option sets the HOMEBREW_BUNDLE_NO_LOCK environment variable, by adding it to - ${mkDocOptionLink "environment.variables"}. + . ''; }; @@ -265,70 +262,70 @@ let description = '' Target location for Applications. - Homebrew's default is /Applications. + Homebrew's default is /Applications. ''; }; colorpickerdir = mkNullOrStrOption { description = '' Target location for Color Pickers. - Homebrew's default is ~/Library/ColorPickers. + Homebrew's default is ~/Library/ColorPickers. ''; }; prefpanedir = mkNullOrStrOption { description = '' Target location for Preference Panes. - Homebrew's default is ~/Library/PreferencePanes. + Homebrew's default is ~/Library/PreferencePanes. ''; }; qlplugindir = mkNullOrStrOption { description = '' Target location for QuickLook Plugins. - Homebrew's default is ~/Library/QuickLook. + Homebrew's default is ~/Library/QuickLook. ''; }; mdimporterdir = mkNullOrStrOption { description = '' Target location for Spotlight Plugins. - Homebrew's default is ~/Library/Spotlight. + Homebrew's default is ~/Library/Spotlight. ''; }; dictionarydir = mkNullOrStrOption { description = '' Target location for Dictionaries. - Homebrew's default is ~/Library/Dictionaries. + Homebrew's default is ~/Library/Dictionaries. ''; }; fontdir = mkNullOrStrOption { description = '' Target location for Fonts. - Homebrew's default is ~/Library/Fonts. + Homebrew's default is ~/Library/Fonts. ''; }; servicedir = mkNullOrStrOption { description = '' Target location for Services. - Homebrew's default is ~/Library/Services. + Homebrew's default is ~/Library/Services. ''; }; input_methoddir = mkNullOrStrOption { description = '' Target location for Input Methods. - Homebrew's default is ~/Library/Input Methods. + Homebrew's default is ~/Library/Input Methods. ''; }; internet_plugindir = mkNullOrStrOption { description = '' Target location for Internet Plugins. - Homebrew's default is ~/Library/Internet Plug-Ins. + Homebrew's default is ~/Library/Internet Plug-Ins. ''; }; audio_unit_plugindir = mkNullOrStrOption { @@ -336,28 +333,28 @@ let Target location for Audio Unit Plugins. Homebrew's default is - ~/Library/Audio/Plug-Ins/Components. + ~/Library/Audio/Plug-Ins/Components. ''; }; vst_plugindir = mkNullOrStrOption { description = '' Target location for VST Plugins. - Homebrew's default is ~/Library/Audio/Plug-Ins/VST. + Homebrew's default is ~/Library/Audio/Plug-Ins/VST. ''; }; vst3_plugindir = mkNullOrStrOption { description = '' Target location for VST3 Plugins. - Homebrew's default is ~/Library/Audio/Plug-Ins/VST3. + Homebrew's default is ~/Library/Audio/Plug-Ins/VST3. ''; }; screen_saverdir = mkNullOrStrOption { description = '' Target location for Screen Savers. - Homebrew's default is ~/Library/Screen Savers. + Homebrew's default is ~/Library/Screen Savers. ''; }; language = mkNullOrStrOption { @@ -481,7 +478,7 @@ let visible = "shallow"; # so that options from `homebrew.caskArgs` aren't repeated. description = '' Arguments passed to brew install --cask when installing this cask. See - ${mkDocOptionLink "homebrew.caskArgs"} for the available options. + for the available options. ''; }; greedy = mkNullOrBoolOption { @@ -523,12 +520,12 @@ in Note that enabling this option does not install Homebrew, see the Homebrew website for installation instructions. - Use the ${mkDocOptionLink "homebrew.brews"}, ${mkDocOptionLink "homebrew.casks"}, - ${mkDocOptionLink "homebrew.masApps"}, and ${mkDocOptionLink "homebrew.whalebrews"} options + Use the , , + , and options to list the Homebrew formulae, casks, Mac App Store apps, and Docker containers you'd like to - install. Use the ${mkDocOptionLink "homebrew.taps"} option, to make additional formula + install. Use the option, to make additional formula repositories available to Homebrew. This module uses those options (along with the - ${mkDocOptionLink "homebrew.caskArgs"} options) to generate a Brewfile that + options) to generate a Brewfile that nix-darwin passes to the brew bundle command during system activation. @@ -536,10 +533,10 @@ in and all formulae, as well as upgrading anything that's already installed, so that repeated invocations of darwin-rebuild switch (without any change to the configuration) are idempotent. You can modify this behavior using the options under - ${mkDocOptionLink "homebrew.onActivation"}. + . This module also provides a few options for modifying how Homebrew commands behave when - you manually invoke them, under ${mkDocOptionLink "homebrew.global"} + you manually invoke them, under ''; brewPrefix = mkOption { @@ -595,7 +592,7 @@ in Taps defined as strings, e.g., "user/repo", are a shorthand for: - { name = "user/repo"; } + { name = "user/repo"; } ''; }; @@ -610,7 +607,7 @@ in ''; description = '' Arguments passed to brew install --cask for all casks listed in - ${mkDocOptionLink "homebrew.casks"}. + . ''; }; @@ -644,7 +641,7 @@ in Formulae defined as strings, e.g., "imagemagick", are a shorthand for: - { name = "imagemagick"; } + { name = "imagemagick"; } ''; }; @@ -675,7 +672,7 @@ in Casks defined as strings, e.g., "google-chrome", are a shorthand for: - { name = "google-chrome"; } + { name = "google-chrome"; } ''; }; @@ -692,12 +689,12 @@ in Applications to install from Mac App Store using mas. When this option is used, "mas" is automatically added to - ${mkDocOptionLink "homebrew.brews"}. + . Note that you need to be signed into the Mac App Store for mas to successfully install and upgrade applications, and that unfortunately apps removed from this option will not be uninstalled automatically even if - ${mkDocOptionLink "homebrew.onActivation.cleanup"} is set to "uninstall" + is set to "uninstall" or "zap" (this is currently a limitation of Homebrew Bundle). For more information on mas see: @@ -713,7 +710,7 @@ in List of Docker images to install using whalebrew. When this option is used, "whalebrew" is automatically added to - ${mkDocOptionLink "homebrew.brews"}. + . For more information on whalebrew see: github.com/whalebrew/whalebrew. diff --git a/modules/nix/default.nix b/modules/nix/default.nix index a880941..6c61acc 100644 --- a/modules/nix/default.nix +++ b/modules/nix/default.nix @@ -173,11 +173,11 @@ in useDaemon = mkOption { type = types.bool; default = false; - description = " + description = '' If set, Nix will use the daemon to perform operations. Use this instead of services.nix-daemon.enable if you don't wan't the daemon service to be managed for you. - "; + ''; }; distributedBuilds = mkOption { @@ -594,7 +594,7 @@ in then Nix will use a binary from a binary cache if and only if it is signed by any of the keys listed here. By default, only the key for - cache.nixos.org is included. + cache.nixos.org is included. ''; }; @@ -650,8 +650,7 @@ in for avalaible options. The value declared here will be translated directly to the key-value pairs Nix expects. - - + Nix configurations defined under will be translated and applied to this option. In addition, configuration specified in which will be appended verbatim to the resulting config file. diff --git a/modules/services/postgresql/default.nix b/modules/services/postgresql/default.nix index bcaf95e..e6feb96 100644 --- a/modules/services/postgresql/default.nix +++ b/modules/services/postgresql/default.nix @@ -88,7 +88,7 @@ in via the Unix socket, and md5 password authentication will be used for users connecting via TCP. Any added rules will be inserted above the default rules. If you'd like to replace the - default rules entirely, you can use lib.mkForce in your + default rules entirely, you can use lib.mkForce in your module. ''; }; @@ -159,7 +159,7 @@ in For more information on how to specify the target and on which privileges exist, see the GRANT syntax. - The attributes are used as GRANT ''${attrValue} ON ''${attrName}. + The attributes are used as GRANT ''${attrValue} ON ''${attrName}. ''; example = literalExpression '' { @@ -237,8 +237,8 @@ in for an overview of postgresql.conf. - String values will automatically be enclosed in single quotes. Single quotes will be - escaped with two single quotes as described by the upstream documentation linked above. + String values will automatically be enclosed in single quotes. Single quotes will be + escaped with two single quotes as described by the upstream documentation linked above. ''; example = literalExpression '' diff --git a/modules/services/synergy/default.nix b/modules/services/synergy/default.nix index f7503da..2ca97a0 100644 --- a/modules/services/synergy/default.nix +++ b/modules/services/synergy/default.nix @@ -23,9 +23,9 @@ in enable = mkOption { default = false; type = types.bool; - description = " + description = '' Whether to enable the Synergy client (receive keyboard and mouse events from a Synergy server). - "; + ''; }; screenName = mkOption { default = ""; diff --git a/modules/system/defaults/NSGlobalDomain.nix b/modules/system/defaults/NSGlobalDomain.nix index 3fb8db0..a23737e 100644 --- a/modules/system/defaults/NSGlobalDomain.nix +++ b/modules/system/defaults/NSGlobalDomain.nix @@ -229,7 +229,8 @@ in { type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Keyboard + Apple menu > System Preferences > Keyboard + If you press and hold certain keyboard keys when in a text area, the key’s character begins to repeat. For example, the Delete key continues to remove text for as long as you hold it down. @@ -241,7 +242,8 @@ in { type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Keyboard + Apple menu > System Preferences > Keyboard + If you press and hold certain keyboard keys when in a text area, the key’s character begins to repeat. For example, the Delete key continues to remove text for as long as you hold it down. @@ -285,7 +287,8 @@ in { type = types.nullOr floatWithDeprecationError; default = null; description = '' - # Apple menu > System Preferences > Sound + Apple menu > System Preferences > Sound + Sets the beep/alert volume level from 0.000 (muted) to 1.000 (100% volume). 75% = 0.7788008 @@ -300,7 +303,8 @@ in { type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Sound + Apple menu > System Preferences > Sound + Make a feedback sound when the system volume changed. This setting accepts the integers 0 or 1. Defaults to 1. ''; diff --git a/modules/system/defaults/alf.nix b/modules/system/defaults/alf.nix index f62ead2..96a9806 100644 --- a/modules/system/defaults/alf.nix +++ b/modules/system/defaults/alf.nix @@ -8,7 +8,8 @@ with lib; type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Security and Privacy > Firewall + Apple menu > System Preferences > Security and Privacy > Firewall + Enable the internal firewall to prevent unauthorised applications, programs and services from accepting incoming connections. @@ -22,7 +23,8 @@ with lib; type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Security and Privacy > Firewall + Apple menu > System Preferences > Security and Privacy > Firewall + Allows any signed Application to accept incoming requests. Default is true. 0 = disabled @@ -34,7 +36,8 @@ with lib; type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Security and Privacy > Firewall + Apple menu > System Preferences > Security and Privacy > Firewall + Allows any downloaded Application that has been signed to accept incoming requests. Default is 0. 0 = disabled @@ -46,7 +49,8 @@ with lib; type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Security and Privacy > Firewall + Apple menu > System Preferences > Security and Privacy > Firewall + Enable logging of requests made to the firewall. Default is 0. 0 = disabled @@ -58,7 +62,8 @@ with lib; type = types.nullOr types.int; default = null; description = '' - # Apple menu > System Preferences > Security and firewall + Apple menu > System Preferences > Security and firewall + Drops incoming requests via ICMP such as ping requests. Default is 0. 0 = disabled diff --git a/modules/system/defaults/loginwindow.nix b/modules/system/defaults/loginwindow.nix index 0194cc1..5f0491a 100644 --- a/modules/system/defaults/loginwindow.nix +++ b/modules/system/defaults/loginwindow.nix @@ -8,7 +8,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Displays login window as a name and password field instead of a list of users. Default is false. ''; @@ -18,7 +19,8 @@ with lib; type = types.nullOr types.str; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Auto login the supplied user on boot. Default is Off. ''; }; @@ -27,7 +29,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Allow users to login to the machine as guests using the Guest account. Default is true. ''; }; @@ -44,7 +47,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Hides the Shut Down button on the login screen. Default is false. ''; }; @@ -53,7 +57,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Hides the Sleep button on the login screen. Default is false. ''; }; @@ -62,7 +67,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Hides the Restart button on the login screen. Default is false. ''; }; @@ -71,7 +77,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Disables the "Shutdown" option when users are logged in. Default is false. ''; }; @@ -80,7 +87,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + If set to true, the Power Off menu item will be disabled when the user is logged in. Default is false. ''; }; @@ -89,7 +97,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Users and Groups > Login Options + Apple menu > System Preferences > Users and Groups > Login Options + Disables the “Restart” option when users are logged in. Default is false. ''; }; diff --git a/modules/system/defaults/spaces.nix b/modules/system/defaults/spaces.nix index 8f256f3..ac2355b 100644 --- a/modules/system/defaults/spaces.nix +++ b/modules/system/defaults/spaces.nix @@ -8,7 +8,8 @@ with lib; type = types.nullOr types.bool; default = null; description = '' - # Apple menu > System Preferences > Mission Control + Apple menu > System Preferences > Mission Control + Displays have separate Spaces (note a logout is required before this setting will take effect). diff --git a/modules/system/patches.nix b/modules/system/patches.nix index 452ed3b..0b56681 100644 --- a/modules/system/patches.nix +++ b/modules/system/patches.nix @@ -29,9 +29,9 @@ in description = '' Set of patches to apply to /. - - This can modify everything so use with caution. - + + This can modify everything so use with caution. + Useful for safely changing system files. Unlike the etc module this won't remove or modify files with unexpected content. -- cgit v1.2.3