From 4c1cfbdb844babe1054c7f365eac337396092d60 Mon Sep 17 00:00:00 2001 From: pennae Date: Fri, 30 Dec 2022 20:43:53 +0100 Subject: modules: add mkAliasOptionModuleMD mkAliasOptionModule should not default to mdDoc descriptions because that can break out-of-tree users of documentation infrastructure. add an explicitly-MD variant for now, to be removed some time after the MD transition is complete. --- lib/default.nix | 3 ++- lib/modules.nix | 13 +++++++++++-- nixos/lib/make-options-doc/mergeJSON.py | 8 +++++--- nixos/modules/config/users-groups.nix | 4 ++-- nixos/modules/rename.nix | 2 +- nixos/modules/services/networking/ssh/sshd.nix | 4 ++-- nixos/modules/services/torrent/transmission.nix | 4 ++-- nixos/modules/services/x11/picom.nix | 2 +- 8 files changed, 26 insertions(+), 14 deletions(-) diff --git a/lib/default.nix b/lib/default.nix index 6e1da00badf..40ed723017c 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -131,7 +131,8 @@ let mkAliasAndWrapDefinitions fixMergeModules mkRemovedOptionModule mkRenamedOptionModule mkRenamedOptionModuleWith mkMergedOptionModule mkChangedOptionModule - mkAliasOptionModule mkDerivedConfig doRename; + mkAliasOptionModule mkDerivedConfig doRename + mkAliasOptionModuleMD; inherit (self.options) isOption mkEnableOption mkSinkUndeclaredOptions mergeDefaultOption mergeOneOption mergeEqualOption mergeUniqueOption getValues getFiles diff --git a/lib/modules.nix b/lib/modules.nix index caabfee5710..166c24a3a05 100644 --- a/lib/modules.nix +++ b/lib/modules.nix @@ -1108,6 +1108,15 @@ rec { visible = true; warn = false; use = id; + wrapDescription = lib.id; + }; + + /* Transitional version of mkAliasOptionModule that uses MD docs. */ + mkAliasOptionModuleMD = from: to: doRename { + inherit from to; + visible = true; + warn = false; + use = id; }; /* mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b @@ -1130,7 +1139,7 @@ rec { (opt.highestPrio or defaultOverridePriority) (f opt.value); - doRename = { from, to, visible, warn, use, withPriority ? true }: + doRename = { from, to, visible, warn, use, withPriority ? true, wrapDescription ? lib.mdDoc }: { config, options, ... }: let fromOpt = getAttrFromPath from options; @@ -1141,7 +1150,7 @@ rec { { options = setAttrByPath from (mkOption { inherit visible; - description = lib.mdDoc "Alias of {option}`${showOption to}`."; + description = wrapDescription "Alias of {option}`${showOption to}`."; apply = x: use (toOf config); } // optionalAttrs (toType != null) { type = toType; diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 750cd24fc65..1e06fe92a22 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -306,14 +306,16 @@ if hasDocBookErrors: print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " + "NixOS is in the process of migrating from DocBook to Markdown, and " + "DocBook is disallowed for in-tree modules. To change your contribution to "+ - "use Markdown, apply mdDoc and literalMD. For example:\n" + + "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " + + "functions where they are available. For example:\n" + "\n" + " example.foo = mkOption {\n" + " description = lib.mdDoc ''your description'';\n" + " defaultText = lib.literalMD ''your description of default'';\n" + - " }\n" + + " };\n" + "\n" + - " example.enable = mkEnableOption (lib.mdDoc ''your thing'');", + " example.enable = mkEnableOption (lib.mdDoc ''your thing'');\n" + + " imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];", file = sys.stderr) if hasErrors: diff --git a/nixos/modules/config/users-groups.nix b/nixos/modules/config/users-groups.nix index 19319b9309c..76092e738eb 100644 --- a/nixos/modules/config/users-groups.nix +++ b/nixos/modules/config/users-groups.nix @@ -444,8 +444,8 @@ let in { imports = [ - (mkAliasOptionModule [ "users" "extraUsers" ] [ "users" "users" ]) - (mkAliasOptionModule [ "users" "extraGroups" ] [ "users" "groups" ]) + (mkAliasOptionModuleMD [ "users" "extraUsers" ] [ "users" "users" ]) + (mkAliasOptionModuleMD [ "users" "extraGroups" ] [ "users" "groups" ]) (mkRenamedOptionModule ["security" "initialRootPassword"] ["users" "users" "root" "initialHashedPassword"]) ]; diff --git a/nixos/modules/rename.nix b/nixos/modules/rename.nix index aef42d0f4db..d88baac7a5d 100644 --- a/nixos/modules/rename.nix +++ b/nixos/modules/rename.nix @@ -14,7 +14,7 @@ with lib; # This alias module can't be where _module.check is defined because it would # be added to submodules as well there - (mkAliasOptionModule [ "environment" "checkConfigurationOptions" ] [ "_module" "check" ]) + (mkAliasOptionModuleMD [ "environment" "checkConfigurationOptions" ] [ "_module" "check" ]) # Completely removed modules (mkRemovedOptionModule [ "environment" "blcr" "enable" ] "The BLCR module has been removed") diff --git a/nixos/modules/services/networking/ssh/sshd.nix b/nixos/modules/services/networking/ssh/sshd.nix index af8200c7e29..37d7518ab3c 100644 --- a/nixos/modules/services/networking/ssh/sshd.nix +++ b/nixos/modules/services/networking/ssh/sshd.nix @@ -79,8 +79,8 @@ in { imports = [ - (mkAliasOptionModule [ "services" "sshd" "enable" ] [ "services" "openssh" "enable" ]) - (mkAliasOptionModule [ "services" "openssh" "knownHosts" ] [ "programs" "ssh" "knownHosts" ]) + (mkAliasOptionModuleMD [ "services" "sshd" "enable" ] [ "services" "openssh" "enable" ]) + (mkAliasOptionModuleMD [ "services" "openssh" "knownHosts" ] [ "programs" "ssh" "knownHosts" ]) (mkRenamedOptionModule [ "services" "openssh" "challengeResponseAuthentication" ] [ "services" "openssh" "kbdInteractiveAuthentication" ]) ]; diff --git a/nixos/modules/services/torrent/transmission.nix b/nixos/modules/services/torrent/transmission.nix index 43782338483..11a9bb850c4 100644 --- a/nixos/modules/services/torrent/transmission.nix +++ b/nixos/modules/services/torrent/transmission.nix @@ -19,8 +19,8 @@ in imports = [ (mkRenamedOptionModule ["services" "transmission" "port"] ["services" "transmission" "settings" "rpc-port"]) - (mkAliasOptionModule ["services" "transmission" "openFirewall"] - ["services" "transmission" "openPeerPorts"]) + (mkAliasOptionModuleMD ["services" "transmission" "openFirewall"] + ["services" "transmission" "openPeerPorts"]) ]; options = { services.transmission = { diff --git a/nixos/modules/services/x11/picom.nix b/nixos/modules/services/x11/picom.nix index 4a0578de09c..1d6f3daa402 100644 --- a/nixos/modules/services/x11/picom.nix +++ b/nixos/modules/services/x11/picom.nix @@ -41,7 +41,7 @@ let in { imports = [ - (mkAliasOptionModule [ "services" "compton" ] [ "services" "picom" ]) + (mkAliasOptionModuleMD [ "services" "compton" ] [ "services" "picom" ]) (mkRemovedOptionModule [ "services" "picom" "refreshRate" ] '' This option corresponds to `refresh-rate`, which has been unused since picom v6 and was subsequently removed by upstream. -- cgit 1.4.1