modules: add mkPackageOptionMD

another transitional option factory, like mkAliasOptionModuleMD.

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;

lib/options.nix

@@ -136,14 +136,19 @@ 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');
  ${if example != null then "example" else null} = literalExpression
  (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

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:
 

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 &quot;name&quot; { default = [ &quot;path&quot; &quot;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:

nixos/lib/make-options-doc/mergeJSON.py

@@ -315,6 +315,7 @@ def is_docbook(o, key):
  " };\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)
 

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) {

nixos/modules/programs/_1password-gui.nix

@@ -27,7 +27,7 @@ in
  '';
  };
 
- package = mkPackageOption pkgs "1Password GUI" {
+ package = mkPackageOptionMD pkgs "1Password GUI" {
  default = [ "_1password-gui" ];
  };
  };

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" ];
  };
  };

nixos/modules/programs/flashrom.nix

@@ -16,7 +16,7 @@ in
  group.
  '';
  };
- package = mkPackageOption pkgs "flashrom" { };
+ package = mkPackageOptionMD pkgs "flashrom" { };
  };
 
  config = mkIf cfg.enable {

nixos/modules/programs/skim.nix

@@ -1,14 +1,14 @@
 { pkgs, config, lib, ... }:
 let
- inherit (lib) mdDoc mkEnableOption mkPackageOption optional optionalString;
+ inherit (lib) mdDoc mkEnableOption mkPackageOptionMD optional optionalString;
  cfg = config.programs.skim;
 in
 {
  options = {
  programs.skim = {
  fuzzyCompletion = mkEnableOption (mdDoc "fuzzy completion with skim");
  keybindings = mkEnableOption (mdDoc "skim keybindings");
- package = mkPackageOption pkgs "skim" {};
+ package = mkPackageOptionMD pkgs "skim" {};
  };
  };
 

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" ];
  };
 

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;

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 ''

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" ];

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;

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.";

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;

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";

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;

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;

nixos/modules/services/x11/window-managers/katriawm.nix

@@ -1,15 +1,15 @@
 { 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
 {
  ###### interface
  options = {
  services.xserver.windowManager.katriawm = {
  enable = mkEnableOption (mdDoc "katriawm");
- package = mkPackageOption pkgs "katriawm" {};
+ package = mkPackageOptionMD pkgs "katriawm" {};
  };
  };
 

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 {

nixos/modules/system/boot/systemd/initrd.nix

@@ -142,7 +142,7 @@ in {
  '';
  };
 
- package = (mkPackageOption pkgs "systemd" {
+ package = (mkPackageOptionMD pkgs "systemd" {
  default = "systemdStage1";
  }) // {
  visible = false;