Nixpkgs Documentation Conventions: Argument Details, Examples, Figures, and General Formatting

Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values). For example: ```markdown # pkgs.coolFunction {#pkgs.coolFunction} `pkgs.coolFunction` *`name`* *`config`* Description of what `callPackage` does. ## Inputs {#pkgs-coolFunction-inputs} If something's special about `coolFunction`'s general argument handling, you can say so here. Otherwise, just describe the single argument or start the arguments' definition list without introduction. *`name`* (String) : The name of the resulting image. *`config`* (Attribute set) : Introduce the parameter. Maybe you have a test to make sure `{ }` is a sensible default; then you can say: these attributes are optional; `{ }` is a valid argument. `outputHash` (String; _optional_) : A brief explanation including when and when not to pass this attribute. : _Default:_ the output path's hash. ``` Checklist: - Start with a synopsis, to show the order of positional arguments. - Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments. - Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables. - _optional_ attributes have a _`Default:`_ if it's easily described as a value. - _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value. - Nix types aren't in code spans, because they are not code - Nix types are capitalized, to distinguish them from the camelCase Module System types, which _are_ code and behave like functions. #### Examples To define a referenceable figure use the following fencing: ```markdown :::{.example #an-attribute-set-example} # An attribute set example You can add text before ```nix { a = 1; b = 2;} ``` and after code fencing ::: ``` Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents. Though this is not shown in the rendered documentation on nixos.org. #### Figures To define a referenceable figure use the following fencing: ```markdown ::: {.figure #nixos-logo} # NixOS Logo ![NixOS logo](./nixos_logo.png) ::: ``` Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`. Though this is not shown in the rendered documentation on nixos.org. #### Footnotes To add a foonote explanation, use the following syntax: ```markdown Sometimes it's better to add context [^context] in a footnote. [^context]: This explanation will be rendered at the end of the chapter. ``` #### Inline comments Inline comments are supported with following syntax: ```markdown  ``` The comments will not be rendered in the rendered HTML. #### Link reference definitions Links can reference a label, for example, to make the link target reusable: ```markdown ::: {.note} Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable. ::: [url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md ``` This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions). #### Typographic replacements Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15). ## Getting help If you need documentation-specific help or reviews, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on your pull request.

This section elaborates on documentation conventions within Nixpkgs, focusing on the detailed structure for function arguments and their attributes using definition lists. It provides specific stylistic rules for argument documentation, including the use of emphasized code spans for metavariables, regular code spans for attribute names, clear indication of optional attributes with default values or behaviors, and proper capitalization of Nix types without code spans. The document also introduces special fencing for defining referenceable examples and figures, explains how to implement footnotes and inline comments, details link reference definitions, and mentions the enablement of typographic replacements. It concludes by directing users to the `@NixOS/documentation-team` for documentation-specific assistance.