Help section for arguments

[Diaoul]

I added a help kwarg to my argument and got this:

TypeError: __init__() got an unexpected keyword argument 'help'

Is there any particular reason why there is no help kwarg on arguments?
Would you consider adding it? I think metavar could benefit from some help in describing the positional arguments. Like in argparse here

[untitaker]

This is mentioned here: http://click.pocoo.org/4/arguments/#arguments

There's also a screencast by Armin out there that argues that arguments are critical to the command's core functionality and therefore should be documented in the command's docstring.

I don't think this should be changed unless there are new points made for it. You can always add your own stuff via the epilog, but this preference is hardcoded in click and I've come to agree with it.

[Diaoul]

@click.group(help='Nice description of the group')
def file_manager():
    pass


@file_manager.command(help='Create a file or a directory, if PATH ends with a /, a directory will be created.')
@click.argument('path')
def touch():
    pass

Renders as:

Usage: file_manager [OPTIONS] COMMAND [ARGS]...

  Nice description of the group

Options:
  --help  Show this message and exit.

Commands:
  touch  Create a file or a directory, if PATH ends...

That's a design decision I respect but I do not agree with and here are some details why:

1. Command help is trucated
2. I didn't choose where the help is truncated
3. At this point, PATH is not displayed in the usage as it is in a subcommand so it's a little bit confusing to see it for the top level help page
4. How is it prettier to not display something? Having an Arguments section like the Options section would be the (optional) opportunity do add more help
5. When you have multiple arguments you end up creating the equivalent of a section with the argument help in your command help

Let me know if you change your mind.

[untitaker]

The first paragraph is used for the short help.

[Diaoul]

Thanks, I can live with that. I'll end up creating my sections manually but without much overhead.