Improve CLI help #733

Description of the problem, including code/CLI snippet

There's a lot of issues for the CLI help, which makes it difficult to use the CLI at all. Some of them have been already reported:

1. --help does not work properly on sub-commands (gitlab CLI --help not working as expected #381, mostly resolved by Re-enable command specific help messages #732)
2. The usage and help outputs are unreadable, ugly and confusing (CLI: List objects vertically #456, [CLI] improve CLI usage output #545, still unresolved)

But there are others, for instance:

3. When wrong arguments are used (e.g. gitlab group list -x), general usage (for gitlab) is printed by gitlab CLI instead of specific usage for the used action (i.e. gitlab group list).

Gitlab uses argparse for argument parsing and help output. Most of these problems (2. and 3. in particular) seem to be caused by the limitations of the argparse library. I was trying to persuade argparse to provide better help, but I was not able to do that. Most of this bad behaviour is hard-coded in the library, and cannot be changed. The public API is limited, the rest of the API "are considered implementation details".

I'm not an expert for argparse, so I may be wrong, but the help seems to me unfixable while it is based on argparse. Instead I suggest switching to click. I was playing with click, and I was able to configure it so that its help output looks very good even for a script like gitlab. See demo comparison.zip, that compares help output of argparse and click in various situations. In the comparison, note:

• argparse output is appropriate to the arguments in all tests but the last two.

• argparse output looks confusing especially when there are lots of commands (I've counted 27 rows of commands on 80 character console, and this list is printed twice)

• argparse output cannot be customized

• click output looks more standard

• click output can be simply customized (as seen e.g. in demo_click2.py)

Resume

I'd like to know your opinion on this suggested change. I won't be doing anything concerning the migration towards click untill it is clear that the change will be welcome.

Specifications

• python-gitlab version: 1.8.0