diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/development/option-declarations.section.md')
| -rw-r--r-- | nixpkgs/nixos/doc/manual/development/option-declarations.section.md | 99 |
1 files changed, 64 insertions, 35 deletions
diff --git a/nixpkgs/nixos/doc/manual/development/option-declarations.section.md b/nixpkgs/nixos/doc/manual/development/option-declarations.section.md index 8bf73a66456b..3448b07722b8 100644 --- a/nixpkgs/nixos/doc/manual/development/option-declarations.section.md +++ b/nixpkgs/nixos/doc/manual/development/option-declarations.section.md @@ -11,7 +11,7 @@ options = { type = type specification; default = default value; example = example value; - description = "Description for use in the NixOS manual."; + description = lib.mdDoc "Description for use in the NixOS manual."; }; }; ``` @@ -44,26 +44,24 @@ The function `mkOption` accepts the following arguments. : A textual representation of the default value to be rendered verbatim in the manual. Useful if the default value is a complex expression or depends on other values or packages. - Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for - a plain English description in DocBook format. + Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for + a plain English description in [Nixpkgs-flavored Markdown]( + https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format. `example` : An example value that will be shown in the NixOS manual. - You can use `lib.literalExpression` and `lib.literalDocBook` in the same way + You can use `lib.literalExpression` and `lib.literalMD` in the same way as in `defaultText`. `description` -: A textual description of the option, in DocBook format, that will be +: A textual description of the option, in [Nixpkgs-flavored Markdown]( + https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be included in the NixOS manual. During the migration process from DocBook - to CommonMark the description may also be written in CommonMark, but has - to be wrapped in `lib.mdDoc` to differentiate it from DocBook. See - the nixpkgs manual for [the list of CommonMark extensions]( - https://nixos.org/nixpkgs/manual/#sec-contributing-markup) - supported by NixOS documentation. - - New documentation should preferably be written as CommonMark. + it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`. + The description may still be written in DocBook (without any marker), but this + is discouraged and will be deprecated in the future. ## Utility functions for common option patterns {#sec-option-declarations-util} @@ -79,18 +77,20 @@ The option's description is "Whether to enable \<name\>.". For example: ::: {#ex-options-declarations-util-mkEnableOption-magic .example} +### `mkEnableOption` usage ```nix -lib.mkEnableOption "magic" +lib.mkEnableOption (lib.mdDoc "magic") # is like lib.mkOption { type = lib.types.bool; default = false; example = true; - description = "Whether to enable magic."; + description = lib.mdDoc "Whether to enable magic."; } ``` +::: -### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption} +### `mkPackageOption`, `mkPackageOptionMD` {#sec-option-declarations-util-mkPackageOption} Usage: @@ -102,42 +102,77 @@ Creates an Option attribute set for an option that specifies the package a modul **Note**: You shouldn’t necessarily make package options for all of your modules. You can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays). -The default package is specified as a list of strings representing its attribute path in nixpkgs. Because of this, you need to pass nixpkgs itself as the first argument. +The package is specified in the third argument under `default` as a list of strings +representing its attribute path in nixpkgs (or another package set). +Because of this, you need to pass nixpkgs itself (or a subset) as the first argument. + +The second argument may be either a string or a list of strings. +It provides the display name of the package in the description of the generated option +(using only the last element if the passed value is a list) +and serves as the fallback value for the `default` argument. + +To include extra information in the description, pass `extraDescription` to +append arbitrary text to the generated description. +You can also pass an `example` value, either a literal string or an attribute path. + +The default argument can be omitted if the provided name is +an attribute of pkgs (if name is a string) or a +valid attribute path in pkgs (if name is a list). -The second argument is the name of the option, used in the description "The \<name\> package to use.". You can also pass an example value, either a literal string or a package's attribute path. +If you wish to explicitly provide no default, pass `null` as `default`. -You can omit the default path if the name of the option is also attribute path in nixpkgs. +During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed. -::: {#ex-options-declarations-util-mkPackageOption .title} +[]{#ex-options-declarations-util-mkPackageOption} Examples: ::: {#ex-options-declarations-util-mkPackageOption-hello .example} +### Simple `mkPackageOption` usage ```nix -lib.mkPackageOption pkgs "hello" { } +lib.mkPackageOptionMD pkgs "hello" { } # is like lib.mkOption { type = lib.types.package; default = pkgs.hello; defaultText = lib.literalExpression "pkgs.hello"; - description = "The hello package to use."; + description = lib.mdDoc "The hello package to use."; } ``` +::: ::: {#ex-options-declarations-util-mkPackageOption-ghc .example} +### `mkPackageOption` with explicit default and example ```nix -lib.mkPackageOption pkgs "GHC" { +lib.mkPackageOptionMD pkgs "GHC" { default = [ "ghc" ]; - example = "pkgs.haskell.packages.ghc924.ghc.withPackages (hkgs: [ hkgs.primes ])"; + example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])"; } # is like lib.mkOption { type = lib.types.package; default = pkgs.ghc; defaultText = lib.literalExpression "pkgs.ghc"; - example = lib.literalExpression "pkgs.haskell.packages.ghc924.ghc.withPackages (hkgs: [ hkgs.primes ])"; - description = "The GHC package to use."; + example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])"; + description = lib.mdDoc "The GHC package to use."; } ``` +::: + +::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example} +### `mkPackageOption` with additional description text +```nix +mkPackageOption pkgs [ "python39Packages" "pytorch" ] { + extraDescription = "This is an example and doesn't actually do anything."; +} +# is like +lib.mkOption { + type = lib.types.package; + default = pkgs.python39Packages.pytorch; + defaultText = lib.literalExpression "pkgs.python39Packages.pytorch"; + description = "The pytorch package to use. This is an example and doesn't actually do anything."; +} +``` +::: ## Extensible Option Types {#sec-option-declarations-eot} @@ -151,7 +186,7 @@ multiple modules, or as an alternative to related `enable` options. As an example, we will take the case of display managers. There is a central display manager module for generic display manager options and a -module file per display manager backend (sddm, gdm \...). +module file per display manager backend (sddm, gdm ...). There are two approaches we could take with this module structure: @@ -186,9 +221,7 @@ changing the main service module file and the type system automatically enforces that there can only be a single display manager enabled. ::: {#ex-option-declaration-eot-service .example} -::: {.title} -**Example: Extensible type placeholder in the service module** -::: +### Extensible type placeholder in the service module ```nix services.xserver.displayManager.enable = mkOption { description = "Display manager to use"; @@ -198,9 +231,7 @@ services.xserver.displayManager.enable = mkOption { ::: ::: {#ex-option-declaration-eot-backend-gdm .example} -::: {.title} -**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module** -::: +### Extending `services.xserver.displayManager.enable` in the `gdm` module ```nix services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "gdm" ]); @@ -209,9 +240,7 @@ services.xserver.displayManager.enable = mkOption { ::: ::: {#ex-option-declaration-eot-backend-sddm .example} -::: {.title} -**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module** -::: +### Extending `services.xserver.displayManager.enable` in the `sddm` module ```nix services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "sddm" ]); |