Click: Adding custom --help content sections

[stevekuznetsov]

In a CLI am developing using Click I would like to have an Examples: section to complement the Usage: section. Sample output would look something like:

Usage: my-tool my-command [OPTIONS]

    Does something.

    Some explanation of more complicated use-cases.

Examples:
    Do something simple
    $ my-tool my-command --default

    Do something complicated
    $ my-tool my-command --some --other --set --of --options

Options:
    --default  doc
    --some     doc
    --other    doc
    --set      doc
    --of       doc
    --options  doc

Is this possible? What is the suggested way to do this?

[stevekuznetsov]

Adding my Examples: section into my docstring does not result in the correct level of indentation:

@click.command()
def my-command():
    '''
    Does something.

    Some explanation of more complicated use-cases.

\b
Examples:
    Do something simple
    $ my-tool my-command --default
\b
    Do something complicated
    $ my-tool my-command --some --other --set --of --options
    '''
    pass

Results in:

$ my-tool my-command --help
Usage: my-tool my-command [OPTIONS]
    Does something.

    Some explanation of more complicated use-cases.

  Examples:
    Do something simple
    $ my-tool my-command --default

    Do something complicated
    $ my-tool my-command --some --other --set --of --options

[untitaker]

This is currently not possible. We might want to add this with a custom decorator or additional option instead of relying on more special characters.

[stevekuznetsov]

@untitaker thanks for the quick reply!

A custom field created with a decorator would be great, but I think that perhaps the Examples field should be available as a first-class citizen, as in my opinion a CLI without example usage is more difficult to use. Often users starting out simply want to know "how do I do THIS" and only delve into the available options, etc. later.

[stevekuznetsov]

If an Examples field were a first-class member, it would be nice if proper practice were to never use a string literal as the command name in the examples, but evaluate it at run-time and therefore allow "copy-paste-able" examples that would take their command from the name used to invoke it. This would also allow for refactoring command structures to be less labor-intensive.

[untitaker]

If we're going this far, this might be a candidate for https://github.com/click-contrib

[dagheyman]

Very interested in this feature as well. I think it is a common and useful pattern to include examples in the help.