metavar in docs does not match metavar in help output about sphinx-click HOT 2 CLOSED

Many thanks for the thorough answer @stephenfin. Didn’t know it was a limitation from Sphinx. It’s a bit sad that I can’t have both help prompts be the same, but I guess it’s not a big problem :)

from sphinx-click.

We can't do this, at least not entirely. We're relying on directives from the Sphinx standard domain under the hood. These have certain requirements around formatting. Relevant to this issue, the option directive insists that "[o]ption argument names should be enclosed in angle brackets." (reference). We need to generate our own defaults, as you can see here. Now we could change the default metavar used for special cases such as the type=click.Path example you gave, but I don't think that extra logic is necessarily worth it: things will already look different.

For references, looking at the example in the docs, on the command line I see:

❯ python examples/commands/cli.py --help
Usage: cli.py [OPTIONS] ARG

  A sample command.

Options:
  --param TEXT                A sample option
  --another [FOO]             Another option
  --choice [Option1|Option2]  A sample option with choices
  --numeric-choice <choice>   A sample option with numeric choices
  --flag                      A boolean flag
  --config FILE
  --help                      Show this message and exit.

While in the docs I see:

--param <param>
    A sample option
--another <FOO>
    Another option
--choice <choice>
    A sample option with choices
    Options:
        Option1 | Option2
--numeric-choice <choice>
    A sample option with numeric choices
    Options:
        1 | 2 | 3
--flag
    A boolean flag
--config <config>

from sphinx-click.