nixdoc
2 min read
Generates CommonMark (Markdown) documentation from Nix library functions with doc comments. Used in the nixpkgs lib documentation pipeline.
Comment format
This tool implements a subset of the doc-comment standard specified in RFC-145/doc-comments. But, it is currently limited to generating documentation for statically analysable attribute paths only. In the future, it could be the role of a Nix interpreter to obtain the values to be documented and their doc-comments.
It is important to start doc-comments with the additional asterisk (*) -> /** which renders as a doc-comment.
The content of the doc-comment should conform to the Commonmark specification.
Example
The following is an example of markdown documentation for new and current users of nixdoc.
Sidenote: Indentation is automatically detected and should be consistent across the content.
If you are used to multiline-strings ('') in nix this should be intuitive to follow.
nix
{
/**
This function adds two numbers
# Example
```nix
add 4 5
=> 9
```
# Type
```
add :: Number -> Number -> Number
```
# Arguments
a
: The first number
b
: The second number
*/
add = a: b: a + b;
}
Note: Within nixpkgs the convention of using definition-lists for documenting arguments has been established.
Usage
sh
nixdoc \
--category "strings" \
--description "String manipulation functions" \
--file lib/strings.nix \
> docs/strings.md
Flags
| Flag | Description |
|---|---|
-p / --prefix <PREFIX> | Prefix for the category (e.g. 'lib' or 'utils') |
-j / --json-output | Whether to output JSON |
--file / -f | Nix file to document |
--category / -c | Category name (used as section heading) |
--description / -d | Category description |
-l / --locs <LOCS> | Path to a file containing location data as JSON |
--lax | Ignore functions without doc comments |