metavar in docs does not match metavar in help output

[jeertmans]

Hello,

Recently, I discovered that the metavar displayed in the docs is not the same as the one displayed in the command-line help output.

E.g., a

@click.option("--config", type=click.Path(dir_okay=False))

will render to --config FILE in the help output, but to --config <config> in the docs.

A practical example can be found here, with the corresponding code here.

Is it possible to make the docs match the help output?

[stephenfin]

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>

[jeertmans]

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 :)