Documentation -- alias of second option, confusing order

[zerothi]

This is mainly a problem of the documentation:

See here: https://click.palletsprojects.com/en/8.1.x/options/#boolean-flags

I find this:

If you want to define an alias for the second option only, then you will need to use leading whitespace to disambiguate the format string:

Example:

import sys

@click.command()
@click.option('--shout/--no-shout', ' /-S', default=False)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

info --help
Usage: info [OPTIONS]

Options:
  --shout / -S, --no-shout
  --help                    Show this message and exit.

Perhaps it's getting late here, but.. I understand it like this:

• we want to alias the 2nd option, i.e. --no-shout.
• to me the empty space before ' /-S' would mean that there is no short-hand for --shout but -S for --no-shout (that may be weird, but that's how I read it...)
• How can one then create a shorthand for --no-shout, but not --shout?

I have tried:

@click.option('--shout/--no-shout', '-S/ ', default=False)
 
$> info --help
  -S, --shout / --no-shout

Which is ok, but still a bit weird. It seems it can only be used to select the order of the short-hand function for the documentation. Perhaps this is intended, but I find the above quite confusing?