Advanced options

[roberth]

Project description

Add a new optional attribute to mkOption called advanced, which indicates options that are not needed in a typical configuration.

Context

Simple is good, but real life gets a vote. As modules gain users, their needs need to be met, and every now and then, that means adding options to cover their use cases peculiarities. However, large numbers of options make the documentation harder to navigate. While a new module's options are often understood at a glance, the same can not be said for a module with 30 options. In such cases, and even at a smaller scale, it would be helpful to provide hints which options are relevant to most users, as opposed to which ones only exist to support rather specific use cases, or which are consumed mostly by other modules rather than user configuration.

Implementation

• Add the advanced flag to mkOption. Options are not advanced by default.

Future work

• Highlight non-advanced options in NixOS search
• Bias the NixOS search to prefer non-advanced options (to a small degree)
• Add a marker to advanced options in generated markdown docs

Maintainers

@infinisil @roberth

[teto]

the same can not be said for a module with 30 options.

Isn't that a strawman though ? In my experience most modules have a very limited number of options eg. <= 10 and because there are so few you want to see all of them since they are all important. If you need 30 options then you are better writing the config yourself IMO or out of tree module. The "settings" format is a nice escape hatch too.

[roberth]

I might have exaggerated by saying 30. I didn't suggest hiding any. We already have that functionality with internal and visibility.

see all of them since they are all important.

I don't know. Is boot.loader.grub.font important?

writing the config yourself or out of tree module

What if I'm the maintainer and I'm happy to provide the functionality?

The "settings" format is a nice escape hatch too.

We have plenty of options that aren't simple configuration file entries.

[Majiir]

The documentation is difficult to navigate even if all modules have 3-5 options each. There is not (AFAIK, please show me to be wrong!) a nice tree view of options or other good ways to explore the options list.

I think "advanced" is too ambiguous and there is no clear boundary between what should be "advanced" or "simple" options. I could see markers like "experimental", "unstable" or "broken" as statements about the readiness or maintenance status of an option.

[teto]

I think "advanced" is too ambiguous and there is no clear boundary between what should be "advanced" or "simple" options. I could see markers like "experimental", "unstable" or "broken" as statements about the readiness or maintenance status of an option.

I dont think I have met an "experimental", "unstable" or "broken" module option, it's always worked pretty decently, and when it didn't it was a bug so it wouldn't have been marked as one of those tags anyway.

I agree that the presentation of the manpage could be improved though, in a treeview as you suggest or removing the common prefix "programs"/"services" after the iteration. I dont have a clear idea but that could be useful.

[Majiir]

I dont think I have met an "experimental"

Search "experimental" in the manual and you'll find plenty. A few that come to mind:

• boot.initrd.systemd.enable
• networking.useNetworkd
• hardware.nvidia.powerManagement

"unstable"

IIRC there are some hidden options with an unstable interface while they are refined. I might be making this up.

"broken"

Take power.ups for example: Its options are "incomplete" at best, requiring config files to be manually created. I'd argue these are "broken" because it's exceedingly difficult to use these options for any useful purpose. That's not because of a single bug, but because the whole module is poorly set up.

---

But I think I'm derailing the conversation here. The point was simply that statements like "experimental", "broken", "unstable" are statements about nixpkgs maintenance. Maybe there are even better, more objective labels. The label "advanced" makes assumptions about the comfort level of a user with a given option, which varies wildly.

[RaitoBezarius]

I'd rather have a tag system, then we get to define a taxonomy to avoid having a large soup, then we define a UX in search.nixos.org.

And then, advanced is nothing but a special case of that tag system.

[RaitoBezarius]

cc @ncfavier as one of the search.nixos.org maintainer.

[l0b0]

I don't know. Is boot.loader.grub.font important?

It absolutely is if you're on a high-res display. Having to sit half a metre away from a big screen is not ideal, and being able to easily find the relevant setting is useful.

Personally I love the idea that all the configuration is surfaced equally, as it gives a good idea what's configurable to what degree, and where there might be room for more. As long as each option is explained in sufficient detail, what would you consider a good reason for marking something as "advanced"?

[roberth]

what would you consider a good reason for marking something as "advanced"?

Things that are unlikely to be required as part of the first few iterations of a new configuration may distract or overwhelm users.

It absolutely is if you're on a high-res display.

Don't we have a high level bool that takes care of that for the whole configuration?

Personally I love the idea that all the configuration is surfaced equally

Treating configuration equally is an important part of making it declarative, so I definitely see value in that. I think we disagree about the degree to which we want to present them equally.

[roberth]

Maybe a better alternative is to provide links to coherent introductory documentation as part of the search results?

I never liked mkEnableOption because it removes an opportunity to provide such info or links, but I'm not sure if most users look at the enable option.

[Majiir]

Maybe a better alternative is to provide links to coherent introductory documentation as part of the search results?

I really like this.

This was my personal evolution as a NixOS user:

1. Start by reading the official documentation: the manual! The Configuration section has so many cool things you can do with NixOS - filesystems, GNOME, Kubernetes, oh my!
2. ...wait, it's only this list of 50 things? That's all you can do with NixOS?!?
3. Oh good, the manual is just incomplete, there's search.nixos.org to the rescue.
4. Y'know, searching man configuration.nix is easier, doesn't lag like the manual, and keeps the options sorted.

What I want as a user is to search for some topic of interest - say, "nat64" - and get a short list of results broken out by package, module, and then individual options if they aren't part of the modules already returned.

For example, I'd expect nat64 to return:

• Modules: networking.jool (because it's in the description of the enable option; arguably, "nat64" should be a keyword of this module)
• Options: services.tayga.tunDevice (because it's the only option that's not in networking.jool that mentions "nat64")
• Packages: tayga, jool-cli, tnat64, jool (but not the several dozen entries for each kernel package set)

Naturally, I would click on the module. And I would expect to see a tree view of this module's options and descriptions, with a heading at the top of the page that highlights at a minimum the enable description (which is good for that module) and preferably more introductory documentation that explains the module with examples. I see this as a convergence of the content that's currently split across the manual and the wiki.

[roberth]

We could move this responsibility out of the core module system, so that it's extensible, and a question that each module system application can answer for itself (where NixOS is one of those applications). See

• 305741