Documenting Scripts — AsyncClick Documentation (8.x)

# Documenting Scripts

Click makes it very easy to document your command line tools. First of all, it automatically generates help pages for you. While these are currently not customizable in terms of their layout, all of the text can be changed.

## Help Texts

Commands and options accept help arguments. In the case of commands, the docstring of the function is automatically used if provided.

Simple example:

And what it looks like:

### Documenting Arguments

`click.argument()` does not take a `help` parameter. This is to follow the general convention of Unix tools of using arguments for only the most necessary things, and to document them in the command help text by referring to them by name.

You might prefer to reference the argument in the description:

And what it looks like:

Or you might prefer to explicitly provide a description of the argument:

And what it looks like:

For more examples, see the examples in Arguments.

## Preventing Rewrapping

The default behavior of Click is to rewrap text based on the width of the terminal. In some circumstances, this can become a problem. The main issue is when showing code examples, where newlines are significant.

Rewrapping can be disabled on a per-paragraph basis by adding a line with solely the `\b` escape marker in it. This line will be removed from the help text and rewrapping will be disabled.

Example:

And what it looks like:

## Truncating Help Texts

Click gets command help text from function docstrings. However if you already use docstrings to document function arguments you may not want to see :param: and :return: lines in your help text.

You can use the `\f` escape marker to have Click truncate the help text after the marker.

Example:

And what it looks like:

## Meta Variables

Options and parameters accept a `metavar` argument that can change the meta variable in the help page. The default version is the parameter name in uppercase with underscores, but can be annotated differently if desired. This can be customized at all levels:

Example:

## Command Short Help

For commands, a short help snippet is generated. By default, it’s the first sentence of the help message of the command, unless it’s too long. This can also be overridden:

And what it looks like:

## Help Parameter Customization

Changelog

New in version 2.0.

The help parameter is implemented in Click in a very special manner. Unlike regular parameters it’s automatically added by Click for any command and it performs automatic conflict resolution. By default it’s called `--help`, but this can be changed. If a command itself implements a parameter with the same name, the default help parameter stops accepting it. There is a context setting that can be used to override the names of the help parameters called `help_option_names`.

This example changes the default parameters to `-h` and `--help` instead of just `--help`:

And what it looks like: