lib.options.optionAttrSetToDocList: add visible = "transparent"

Allows marking an option as invisible, without excluding its sub-options.

In practice, this is similar to `visible = true; internal = true;`,
however it is more explicit and less reliant on implementation details.

lib/options.nix

@@ -116,6 +116,7 @@ rec {
       : Optional, whether the option and/or sub-options show up in the manual.
         Use false to hide the option and any sub-options from submodules.
         Use "shallow" to hide only sub-options.
+        Use "transparent" to hide this option, but not its sub-options.
         Default: true.
 
       `readOnly`
@@ -575,13 +576,14 @@ rec {
       opt:
       let
         name = showOption opt.loc;
+        visible = opt.visible or true;
         docOption = {
           loc = opt.loc;
           inherit name;
           description = opt.description or null;
           declarations = filter (x: x != unknownModule) opt.declarations;
           internal = opt.internal or false;
-          visible = if (opt ? visible && opt.visible == "shallow") then true else opt.visible or true;
+          visible = if isBool visible then visible else visible == "shallow";
           readOnly = opt.readOnly or false;
           type = opt.type.description or "unspecified";
         }
@@ -604,7 +606,7 @@ rec {
             ss = opt.type.getSubOptions opt.loc;
           in
           if ss != { } then optionAttrSetToDocList' opt.loc ss else [ ];
-        subOptionsVisible = docOption.visible && opt.visible or null != "shallow";
+        subOptionsVisible = if isBool visible then visible else visible == "transparent";
       in
       # To find infinite recursion in NixOS option docs:
       # builtins.trace opt.loc

lib/tests/misc.nix

@@ -3232,6 +3232,10 @@ runTests {
                 type = lib.types.submodule submodule;
                 visible = "shallow";
               };
+              transparent = lib.mkOption {
+                type = lib.types.submodule submodule;
+                visible = "transparent";
+              };
               "true" = lib.mkOption {
                 type = lib.types.submodule submodule;
                 visible = true;
@@ -3268,6 +3272,18 @@ runTests {
         visible = true;
         internal = false;
       };
+      transparent = {
+        visible = false;
+        internal = false;
+      };
+      "transparent.foo" = {
+        visible = true;
+        internal = false;
+      };
+      "transparent.<name>.bar" = {
+        visible = true;
+        internal = false;
+      };
       "true" = {
         visible = true;
         internal = false;