diff options
23 files changed, 42 insertions, 24 deletions
diff --git a/lib/default.nix b/lib/default.nix index 40ed723017c6e..5d003d472f434 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -139,7 +139,7 @@ let optionAttrSetToDocList optionAttrSetToDocList' scrubOptionValue literalExpression literalExample literalDocBook showOption showOptionWithDefLocs showFiles - unknownModule mkOption mkPackageOption + unknownModule mkOption mkPackageOption mkPackageOptionMD mdDoc literalMD; inherit (self.types) isType setType defaultTypeMerge defaultFunctor isOptionType mkOptionType; diff --git a/lib/options.nix b/lib/options.nix index 9425e803c0565..ce66bfb9d5d9f 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -136,7 +136,7 @@ rec { let default' = if !isList default then [ default ] else default; in mkOption { type = lib.types.package; - description = lib.mdDoc "The ${name} package to use."; + description = "The ${name} package to use."; default = attrByPath default' (throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs; defaultText = literalExpression ("pkgs." + concatStringsSep "." default'); @@ -144,6 +144,11 @@ rec { (if isList example then "pkgs." + concatStringsSep "." example else example); }; + /* Like mkPackageOption, but emit an mdDoc description instead of DocBook. */ + mkPackageOptionMD = args: name: extra: + let option = mkPackageOption args name extra; + in option // { description = lib.mdDoc option.description; }; + /* This option accepts anything, but it does not produce any result. This is useful for sharing a module across different module sets diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md index f89aae5730682..aa747f47c9c81 100644 --- a/nixos/doc/manual/development/option-declarations.section.md +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -88,7 +88,7 @@ lib.mkOption { } ``` -### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption} +### `mkPackageOption`, `mkPackageOptionMD` {#sec-option-declarations-util-mkPackageOption} Usage: @@ -106,6 +106,8 @@ The second argument is the name of the option, used in the description "The \<na You can omit the default path if the name of the option is also attribute path in nixpkgs. +During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed. + ::: {#ex-options-declarations-util-mkPackageOption .title} Examples: diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml index 2e6a12d530953..cc4893939c280 100644 --- a/nixos/doc/manual/from_md/development/option-declarations.section.xml +++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml @@ -138,7 +138,8 @@ lib.mkOption { } </programlisting> <section xml:id="sec-option-declarations-util-mkPackageOption"> - <title><literal>mkPackageOption</literal></title> + <title><literal>mkPackageOption</literal>, + <literal>mkPackageOptionMD</literal></title> <para> Usage: </para> @@ -172,6 +173,15 @@ mkPackageOption pkgs "name" { default = [ "path" "in&qu You can omit the default path if the name of the option is also attribute path in nixpkgs. </para> + <para> + During the transition to CommonMark documentation + <literal>mkPackageOption</literal> creates an option with a + DocBook description attribute, once the transition is + completed it will create a CommonMark description instead. + <literal>mkPackageOptionMD</literal> always creates an option + with a CommonMark description attribute and will be removed + some time after the transition is completed. + </para> <anchor xml:id="ex-options-declarations-util-mkPackageOption" /> <para> Examples: diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 1e06fe92a223c..7b14af40c313b 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -315,6 +315,7 @@ if hasDocBookErrors: " };\n" + "\n" + " example.enable = mkEnableOption (lib.mdDoc ''your thing'');\n" + + " example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" + " imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];", file = sys.stderr) diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index 64a8f7846b463..e44a9899772f1 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -50,7 +50,7 @@ let (name: value: let wholeName = "${namePrefix}.${name}"; - guard = lib.warn "Attempt to evaluate package ${wholeName} in option documentation; this is not supported and will eventually be an error. Use `mkPackageOption` or `literalExpression` instead."; + guard = lib.warn "Attempt to evaluate package ${wholeName} in option documentation; this is not supported and will eventually be an error. Use `mkPackageOption{,MD}` or `literalExpression` instead."; in if isAttrs value then scrubDerivations wholeName value // optionalAttrs (isDerivation value) { diff --git a/nixos/modules/programs/_1password-gui.nix b/nixos/modules/programs/_1password-gui.nix index 83ef6037fb5a3..27c0d34a2eedf 100644 --- a/nixos/modules/programs/_1password-gui.nix +++ b/nixos/modules/programs/_1password-gui.nix @@ -27,7 +27,7 @@ in ''; }; - package = mkPackageOption pkgs "1Password GUI" { + package = mkPackageOptionMD pkgs "1Password GUI" { default = [ "_1password-gui" ]; }; }; diff --git a/nixos/modules/programs/_1password.nix b/nixos/modules/programs/_1password.nix index 91246150755d5..8537484c7e67d 100644 --- a/nixos/modules/programs/_1password.nix +++ b/nixos/modules/programs/_1password.nix @@ -18,7 +18,7 @@ in programs._1password = { enable = mkEnableOption (lib.mdDoc "the 1Password CLI tool"); - package = mkPackageOption pkgs "1Password CLI" { + package = mkPackageOptionMD pkgs "1Password CLI" { default = [ "_1password" ]; }; }; diff --git a/nixos/modules/programs/flashrom.nix b/nixos/modules/programs/flashrom.nix index ff495558c9e04..294b208a37208 100644 --- a/nixos/modules/programs/flashrom.nix +++ b/nixos/modules/programs/flashrom.nix @@ -16,7 +16,7 @@ in group. ''; }; - package = mkPackageOption pkgs "flashrom" { }; + package = mkPackageOptionMD pkgs "flashrom" { }; }; config = mkIf cfg.enable { diff --git a/nixos/modules/programs/skim.nix b/nixos/modules/programs/skim.nix index 57a5d68ec3d5a..8dadf322606e2 100644 --- a/nixos/modules/programs/skim.nix +++ b/nixos/modules/programs/skim.nix @@ -1,6 +1,6 @@ { pkgs, config, lib, ... }: let - inherit (lib) mdDoc mkEnableOption mkPackageOption optional optionalString; + inherit (lib) mdDoc mkEnableOption mkPackageOptionMD optional optionalString; cfg = config.programs.skim; in { @@ -8,7 +8,7 @@ in programs.skim = { fuzzyCompletion = mkEnableOption (mdDoc "fuzzy completion with skim"); keybindings = mkEnableOption (mdDoc "skim keybindings"); - package = mkPackageOption pkgs "skim" {}; + package = mkPackageOptionMD pkgs "skim" {}; }; }; diff --git a/nixos/modules/programs/streamdeck-ui.nix b/nixos/modules/programs/streamdeck-ui.nix index 113d1d49e151a..4c055029e39b9 100644 --- a/nixos/modules/programs/streamdeck-ui.nix +++ b/nixos/modules/programs/streamdeck-ui.nix @@ -15,7 +15,7 @@ in description = lib.mdDoc "Whether streamdeck-ui should be started automatically."; }; - package = mkPackageOption pkgs "streamdeck-ui" { + package = mkPackageOptionMD pkgs "streamdeck-ui" { default = [ "streamdeck-ui" ]; }; diff --git a/nixos/modules/services/databases/dgraph.nix b/nixos/modules/services/databases/dgraph.nix index 5726851a43f95..887164fa5b943 100644 --- a/nixos/modules/services/databases/dgraph.nix +++ b/nixos/modules/services/databases/dgraph.nix @@ -55,7 +55,7 @@ in services.dgraph = { enable = mkEnableOption (lib.mdDoc "Dgraph native GraphQL database with a graph backend"); - package = lib.mkPackageOption pkgs "dgraph" { }; + package = lib.mkPackageOptionMD pkgs "dgraph" { }; settings = mkOption { type = settingsFormat.type; diff --git a/nixos/modules/services/mail/listmonk.nix b/nixos/modules/services/mail/listmonk.nix index 8b636bd5b1ff6..251362fdd89d3 100644 --- a/nixos/modules/services/mail/listmonk.nix +++ b/nixos/modules/services/mail/listmonk.nix @@ -128,7 +128,7 @@ in { ''; }; }; - package = mkPackageOption pkgs "listmonk" {}; + package = mkPackageOptionMD pkgs "listmonk" {}; settings = mkOption { type = types.submodule { freeformType = tomlFormat.type; }; description = lib.mdDoc '' diff --git a/nixos/modules/services/misc/input-remapper.nix b/nixos/modules/services/misc/input-remapper.nix index 51e1abdc98a08..6353966f5c3ff 100644 --- a/nixos/modules/services/misc/input-remapper.nix +++ b/nixos/modules/services/misc/input-remapper.nix @@ -7,7 +7,7 @@ let cfg = config.services.input-remapper; in options = { services.input-remapper = { enable = mkEnableOption (lib.mdDoc "input-remapper, an easy to use tool to change the mapping of your input device buttons."); - package = options.mkPackageOption pkgs "input-remapper" { }; + package = mkPackageOptionMD pkgs "input-remapper" { }; enableUdevRules = mkEnableOption (lib.mdDoc "udev rules added by input-remapper to handle hotplugged devices. Currently disabled by default due to https://github.com/sezanzeb/input-remapper/issues/140"); serviceWantedBy = mkOption { default = [ "graphical.target" ]; diff --git a/nixos/modules/services/misc/polaris.nix b/nixos/modules/services/misc/polaris.nix index 83da486083b42..70f097f028406 100644 --- a/nixos/modules/services/misc/polaris.nix +++ b/nixos/modules/services/misc/polaris.nix @@ -13,7 +13,7 @@ in services.polaris = { enable = mkEnableOption (lib.mdDoc "Polaris Music Server"); - package = mkPackageOption pkgs "polaris" { }; + package = mkPackageOptionMD pkgs "polaris" { }; user = mkOption { type = types.str; diff --git a/nixos/modules/services/networking/openconnect.nix b/nixos/modules/services/networking/openconnect.nix index 4676b1733af68..5a02bd072257f 100644 --- a/nixos/modules/services/networking/openconnect.nix +++ b/nixos/modules/services/networking/openconnect.nix @@ -116,7 +116,7 @@ let }; in { options.networking.openconnect = { - package = mkPackageOption pkgs "openconnect" { }; + package = mkPackageOptionMD pkgs "openconnect" { }; interfaces = mkOption { description = lib.mdDoc "OpenConnect interfaces."; diff --git a/nixos/modules/services/networking/shellhub-agent.nix b/nixos/modules/services/networking/shellhub-agent.nix index ad33c50f9d633..7cce23cb9c4e3 100644 --- a/nixos/modules/services/networking/shellhub-agent.nix +++ b/nixos/modules/services/networking/shellhub-agent.nix @@ -14,7 +14,7 @@ in enable = mkEnableOption (lib.mdDoc "ShellHub Agent daemon"); - package = mkPackageOption pkgs "shellhub-agent" { }; + package = mkPackageOptionMD pkgs "shellhub-agent" { }; preferredHostname = mkOption { type = types.str; diff --git a/nixos/modules/services/networking/vdirsyncer.nix b/nixos/modules/services/networking/vdirsyncer.nix index 6a069943434da..f9b880c763e3d 100644 --- a/nixos/modules/services/networking/vdirsyncer.nix +++ b/nixos/modules/services/networking/vdirsyncer.nix @@ -71,7 +71,7 @@ in services.vdirsyncer = { enable = mkEnableOption (mdDoc "vdirsyncer"); - package = mkPackageOption pkgs "vdirsyncer" {}; + package = mkPackageOptionMD pkgs "vdirsyncer" {}; jobs = mkOption { description = mdDoc "vdirsyncer job configurations"; diff --git a/nixos/modules/services/networking/webhook.nix b/nixos/modules/services/networking/webhook.nix index b020db6961c32..2a78491941cf9 100644 --- a/nixos/modules/services/networking/webhook.nix +++ b/nixos/modules/services/networking/webhook.nix @@ -36,7 +36,7 @@ in { which execute configured commands for any person or service that knows the URL ''); - package = mkPackageOption pkgs "webhook" {}; + package = mkPackageOptionMD pkgs "webhook" {}; user = mkOption { type = types.str; default = defaultUser; diff --git a/nixos/modules/services/torrent/transmission.nix b/nixos/modules/services/torrent/transmission.nix index 11a9bb850c4ce..752ab91fe6315 100644 --- a/nixos/modules/services/torrent/transmission.nix +++ b/nixos/modules/services/torrent/transmission.nix @@ -174,7 +174,7 @@ in }; }; - package = mkPackageOption pkgs "transmission" {}; + package = mkPackageOptionMD pkgs "transmission" {}; downloadDirPermissions = mkOption { type = with types; nullOr str; diff --git a/nixos/modules/services/x11/window-managers/katriawm.nix b/nixos/modules/services/x11/window-managers/katriawm.nix index 106631792ff4e..9a3fd5f3ca44a 100644 --- a/nixos/modules/services/x11/window-managers/katriawm.nix +++ b/nixos/modules/services/x11/window-managers/katriawm.nix @@ -1,7 +1,7 @@ { config, lib, pkgs, ... }: let - inherit (lib) mdDoc mkEnableOption mkIf mkPackageOption singleton; + inherit (lib) mdDoc mkEnableOption mkIf mkPackageOptionMD singleton; cfg = config.services.xserver.windowManager.katriawm; in { @@ -9,7 +9,7 @@ in options = { services.xserver.windowManager.katriawm = { enable = mkEnableOption (mdDoc "katriawm"); - package = mkPackageOption pkgs "katriawm" {}; + package = mkPackageOptionMD pkgs "katriawm" {}; }; }; diff --git a/nixos/modules/services/x11/window-managers/qtile.nix b/nixos/modules/services/x11/window-managers/qtile.nix index 523642591d947..fc27566d49ee6 100644 --- a/nixos/modules/services/x11/window-managers/qtile.nix +++ b/nixos/modules/services/x11/window-managers/qtile.nix @@ -10,7 +10,7 @@ in options.services.xserver.windowManager.qtile = { enable = mkEnableOption (lib.mdDoc "qtile"); - package = mkPackageOption pkgs "qtile" { }; + package = mkPackageOptionMD pkgs "qtile" { }; }; config = mkIf cfg.enable { diff --git a/nixos/modules/system/boot/systemd/initrd.nix b/nixos/modules/system/boot/systemd/initrd.nix index 196f44ccd783c..d30f61146e189 100644 --- a/nixos/modules/system/boot/systemd/initrd.nix +++ b/nixos/modules/system/boot/systemd/initrd.nix @@ -142,7 +142,7 @@ in { ''; }; - package = (mkPackageOption pkgs "systemd" { + package = (mkPackageOptionMD pkgs "systemd" { default = "systemdStage1"; }) // { visible = false; |