`lib.literalOption` or better option marker rendering

[roberth]

Project description

Add a lib function for the module system, to be used in documentation (ie defaultText, example), to indicate that the value of an option is reused.

The function is a "constructor" (ie returns the argument wrapped with _type = "literalOption";), and it is rendered as a link to the option.

Example

mkOption {
  default = literalOption "services.postgresql.enable";
}

Rendered:

Default:

Value of services.postgresql.enable

Class

The module class could be used to link to options in other parts of the option tree (if they have a class). The physical locations of option documentation could be passed to nixosOptionsDoc as a map from class string to function from option path to url.

Example

mkOption {
  default = literalOption {
    class = "nginx-virtualHost"
    option = "documentRoot";
  };
}

Alternative

Improve the handling of {option}`some.option` in the markdown processor, such that it is rendered as a link. This has the benefit that option references can be written anywhere instead of just two locations.

It requires a similar configuration in nixosOptionDoc as described before, but considering that {option} is already in use and has mixed quality, we'll want to avoid creating broken links. Bad links may be detectable for local references, but requires more docs infrastructure.

Class could be handled by e.g. {option,class=nginx-virtualhost}`documentRoot`

Metadata

Maintainers @infinisil @roberth

[fricklerhandwerk]

Related: https://github.com/NixOS/nixpkgs/issues/127813

[infinisil]

Should probably be literalOption options.services.postgresql.enable, because this allows it to work for submodules too.