Print supported values in synopses, when practical

[numist]

This PR adds support for conditionally expanding argument and subcommand synopses to reflect supported values when there are multiple values and their combined length is not overly onerous.

To use an example from math, this PR changes the current:

USAGE: math <subcommand>

to

USAGE: math <add|multiply|stats>

But does not change the output for commands with a single subcommand or commands with very long subcommands.

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[natecook1000]

Cool! Does this also change the display for an argument/option when an invalid value is provided or the value is missing?

$ fruit_store purchas apple
$ fruit_store apple --ripeness perf
$ fruit_store apple --ripeness

[natecook1000]

It looks like replacing <action> with its values makes it harder to see the correspondence between the usage string and the help descriptions. Are there existing tools that include values in the usage string like this? What would you think of including the argument name – something like:

USAGE: fruit_store [<action: purchase|sample|return>] <fruit> ...

[numist]

I'm certain that I've used a cli before that had this feature, but over the past two weeks I could not remember what it was.

It did have the issue you describe though, and I like your solution! Another possibility is that ArgumentParser only expand values when showing a short help (such as gets printed after a ValidationError) and leaving the behaviour as-is when printing the complete --help output.

[numist]

Ohh the tool I'm thinking of is something I use frequently at work. Instead of an expanded --help, it explains multiple subcommands at once and then refers to a man page. To paraphrase:

> foo bar --help
Usage:
foo alice      --baz <baz_id> [--[no-]qux] [--[no-]thbpt] [--fix]
foo bar        --baz <baz_id> [--[no-]qux] [--blarpy <blarpy>] [--minimal | --details] [--[no-]box] [--[no-]link] [--eh|--bee|--see] (--regex|--exact|--contains|--suffix) <search_term>
…

foo sub-commands and options are documented in the manual page (`man foo`).

I was thinking ArgumentParser's top level help for commands with subcommands is a bit spartan, I wonder if this tool is on to something…

[natecook1000]

Likewise, it seems like this loses the context that add/multiply/stats are subcommands.

[rauhul]

I'm not fully convinced this is a readability improvement over the valid options appearing below.

IMO the synopsis should be succinct and the options below should contain the details.

[numist]

Reasonable! What got me started down this path was the idea that it should be possible to write a correct invocation of a command after the briefest possible glance at its usage, which is necessarily at odds with brevity (and introduces repetition).

Another possibility is that ArgumentParser could expand values only when the options are not explained ("short help", in this reply to Nate)

[natecook1000]

Coming back to this – what would you think about reducing the scope, so that this adds the supported values for options (e.g. [--ripeness <under|perfect|over>]) but doesn't replace the placeholder name for arguments or subcommands? The option value change seems purely additive, but we'll need to discuss the other two a bit more. Thanks!

[numist]

Done!