Skip to content

option: render descriptions, defaults, etc. in color #26

@water-sucks

Description

@water-sucks

Feature Description

There are certain fields within the option description (such as the description especially) that have formatted values meant for use in HTML rendering.

Take for example the description for _module.args:

Additional arguments passed to each module in addition to ones
like `lib`, `config`,
and `pkgs`, `modulesPath`.

This option is also available to all submodules. Submodules do not
inherit args from their parent module, nor do they provide args to
their parent module or sibling submodules. The sole exception to
this is the argument `name` which is provided by
parent modules to a submodule and contains the attribute name
the submodule is bound to, or a unique generated name if it is
not bound to an attribute.

Some arguments are already passed by default, of which the
following *cannot* be changed with this option:
- {var}`lib`: The nixpkgs library.
- {var}`config`: The results of all options after merging the values from all modules together.
- {var}`options`: The options declared in all modules.
- {var}`specialArgs`: The `specialArgs` argument passed to `evalModules`.
- All attributes of {var}`specialArgs`

  Whereas option values can generally depend on other option values
  thanks to laziness, this does not apply to `imports`, which
  must be computed statically before anything else.

  For this reason, callers of the module system can provide `specialArgs`
  which are available during import resolution.

  For NixOS, `specialArgs` includes
  {var}`modulesPath`, which allows you to import
  extra modules from the nixpkgs package tree without having to
  somehow make the module aware of the location of the
  `nixpkgs` or NixOS directories.
  \```
  { modulesPath, ... }: {
    imports = [
      (modulesPath + "/profiles/minimal.nix")
    ];
  }
  \```

For NixOS, the default value for this option includes at least this argument:
- {var}`pkgs`: The nixpkgs package set according to
  the {option}`nixpkgs.pkgs` option.

This formatting can make it unclear what is being displayed, since this is on the command line. We should sanitize this in order to remove the nixpkgs-specific formatting ({var}, {option}, etc.), parse the markdown, and if possible, render it in color if NO_COLOR=1 is not set.

If possible, we can sanitize this at the source, before it ever makes it into the option cache. But this may make the Nix expression used to generate the cache harder to maintain and harder to execute within a short timeframe.

Help

Yes

Issues

  • I have checked existing issues and there are no existing ones with the same request.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions