Nixpkgs Documentation Conventions: REPL Formatting, Headings, and Function Argument Documentation

--option substituters file:///tmp/hello-cache /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1 ``` Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell. For the Nix REPL, you should use a format like the following: ```shell nix-repl> builtins.attrNames { a = 1; b = 2; } [ "a" "b" ] ``` Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL. ### Headings for inputs, outputs and examples When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples. Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation. The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on. An example: ``` ## buildImage Some explanation about the function here. Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it. ### Inputs Documentation for the inputs of `buildImage`. Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it. ### Passthru outputs Documentation for any passthru outputs of `buildImage`. ### Examples Note that this is the last nested heading in the `buildImage` section. :::{.example #ex-dockerTools-buildImage} # Using `buildImage` Example of how to use `buildImage` goes here. ::: ``` ### Function arguments 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`* ```.

This document outlines further conventions for Nixpkgs documentation, starting with guidelines for formatting REPL (shell and Nix REPL) inputs and outputs. It then details a mandatory structure for documenting functions, requiring nested headings for 'Inputs,' 'Passthru outputs,' and 'Examples,' always placing examples last and linking to them as needed. Finally, it specifies that function arguments and their attributes should be documented using definition lists, including types, and provides a checklist for proper argument documentation, such as starting with a synopsis and using emphasized code spans for metavariables.