treewide: more defaultText for options #148785
Conversation
github-actions
bot
added
6.topic: nixos
ofborg
bot
added
10.rebuild-darwin: 0
There was a problem hiding this comment.
Regarding not knowing how to show an option path for submodule options, I've wanted this myself before too. It's very nicely possible with this change (unfortunately reverted for now from the PR it's contained in): 1e6a84b.
Do you think you could use a patch like this to simplify many of these changes?
Also an additional correctness benefit of this is that such an approach will also show the correct nested option path if you use all of NixOS as a submodule (e.g. as I'm doing in https://github.com/Infinisil/nixus).
|
Is there something (now or in the future) that can check whether all options have a constant |
pretty much, #149532 introduces hard failures for non-constant documentation attributes in the cached part of the docs build. the uncached part is unrestricted, and we haven't found a satisfying way of making |
nixos no longer ships journalbeat 5 and hasn't since at least 20.09. remove checks for older versions from the module.
adds defaultText for all options that set their default to a path expression using the ubiquitous `cfg` shortcut bindings.
the kubernetes modules cross-reference their config using an additional shortcut binding `top = config.services.kubernetes`, expand those to defaultText like `cfg` previously.
adds defaultText for all options that use `cfg.*` values in their defaults, but only for interpolations with no extra processing (other than toString where necessary)
…faults adds defaultText for options with defaults that use only literals, full config.* paths, and the cfg shortcut binding.
escape interpolations in descriptions where possible, replace them with sufficiently descriptive text elsewhere. also expand cfg.* paths in descriptions.
escape interpolations in examples, or replace them where they are not useful.
some options have default that are best described in prose, such as defaults that depend on the system stateVersion, defaults that are derivations specific to the surrounding context, or those where the expression is much longer and harder to understand than a simple text snippet.
instead of keeping a defaultConfig value around, set that value as the default of the option and explicitly use the option default instead. this also allows us to write a defaultText that makes sense and is in proximity to the definition of the default.
unfortunately we don't have a good way to represent defaults that reference other values of the current submodule, so we just use the relative path of the referenced value and assume that the submodule was declared as `rec`.
easiest way to do this is to move the default expression out and abstract over what is substituted into it, using a dependent value for the default and a descriptive value for defaultText
these are mostly options that use alias bindings, bindings to constants, or bindings to calculated values.
|
Thank you, this looks great! I just turned off docs on one of my systems because of how slow it is ... :). |
like #147441, but handles the bits that are more complicated than copying an expression and surrounding it with quotes.
just this PR alone seems to speed up the docs build by about 15%, which makes for a ~3% improvement on nixos-rebuild on our machine.
Things done
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)nixos/doc/manual/md-to-db.shto update generated release notes