improvements to help

[gregcaporaso]

• -h is shortcut for --help
• calling subcommands (e.g., qiime tools extract or qiime diversity alpha) invokes help

[ebolyen]

ls -h, du -h, df -h, and others all use it to mean --human-readable.
touch is a weird one who uses it to mean --no-dereference.

Whatever we do, so long as we do better than man:

$ man
What manual page do you want?

And similarly:

$  man 1
No manual entry for 1
(Alternatively, what manual page do you want from section 1?)

Can you imagine:

$ qiime
What plugin do you want?

$ qiime foo
No action for foo
(Alternatively, what action do you want from foo?)

<sarcasm> There is clearly a lot of great UX we can borrow from unix utilities. </sarcasm>

[kestrelgorlick]

From what I've seen, there doesn't appear to be a good way to do this. In the click.Command documentation, there isn't a nice option for it, like no_args_is_help. Also, I have found two different issues from people who've had this problem, one here and one here. In the second one, the person who submitted the issue was pointed to this solution which adds a hint when passing command sub-command without --help, but still throws the error. This has been merged, but there must've not been a release since then, because it's not implemented yet. Additionally, the person who submitted the issue made a fix, but it hasn't been merged, as it has conflicts.

Thoughts?

[ebolyen]

Looking into those issues (thanks @Kleptobismol!), I think I agree with what they are doing currently, providing a hint to use --help. It was merged a week or so after their last release, and judging by their frequency of releasing I would expect this will be available soonish.

I am also starting to really wonder if aliasing -h makes sense. Outside of QIIME, I've never seen it used to mean --help and --help is one of the few actually "standard" arguments in UNIX, it seems like we might need to do a lot of work for "nonstandard" behavior.

[gregcaporaso]

Given all of this, we're going to skip these.

[jakereps]

It looks like this may be possible, do we want to try this? (pair-opened w/ @ebolyen)

pallets/click/issues/700

[jairideout]

Pair-closed w/ @gregcaporaso