nixdoc

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.

{
  /**
    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

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