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

[MattSturgeon]

It came up in a discussion that there is a way to mark an option as invisible, or an option's sub-options, but not a way to mark an option as invisible without hiding its sub-options.

Technically, you can mark an option as internal, and this will have a similar effect. That's because, currently, optionAttrSetToDocList will not check internal when deciding whether to recurse into sub-options. However that feels like an implementation detail that I'm uncomfortable relying on. According to their docs, visible and internal have subtly different semantics, too; so I'm uncomfortable using them interchangeably.

This PR expands the test suite to explicitly test how optionAttrSetToDocList handles visible and internal, then adds a new visible = "transparent" value. This new value is used to indicate that the option is not visible, but its sub-options are.

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
    • nix-build lib/tests/release.nix
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

---

Add a 👍 reaction to pull requests you find important.

[roberth]

LGTM, and the test is much appreciated.

We now cover the whole (self:Bool × children:Bool) space and while arguably that would be a cleaner representation (with children defaulting to the value of self), but I'd prefer to save that refactor for a major revision where we can implement it without evaluation memory overhead (virtually all docs things under a single mkOption attr).

I did notice duplicate and out of date docs in the NixOS manual, but that's also out of scope for this PR.

So just that one suggestion and then I think it's ready for merge.

[MattSturgeon]

I did notice duplicate and out of date docs in the NixOS manual, but that's also out of scope for this PR.

I did a quick grep for "shallow" and didn't find anything, hence why I only touched the nixdoc comments.

Looking closer, there's #sec-option-declarations. It seems like visible and internal are currently undocumented in the manual 👀

Personally, I'd like to remove the duplication and generate docs for functions like this using nixdoc, like we do for (e.g.) most of lib.