Allow splitting help message into group sections

[josephlou5]

Hello! Apologies if this is a little unclear; I have a good idea of what I want but am unsure of how to succinctly express it.

I am using a CommandCollection with multiple Groups. When I use the --help option on the top level, I see all of the commands of every group combined in a single list, as expected. However, I'm wondering if it's possible to make it so that the help message shows the commands for each group in individual sections. This only semantically splits the commands into groups, but still allows them to be called at the top level.

Example:

import click

@click.group()
def group1(): pass

@group1.command()
def cmd1(): pass

@click.group()
def group2(): pass

@group2.command()
def cmd2(): pass

cli = click.CommandCollection(sources=[group1, group2])

if __name__ == "__main__":
    cli()

Output:

$ python test.py --help
Usage: test.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  cmd1
  cmd2

Desired output (something like this):

Usage: test.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

group1 Commands:
  cmd1

group2 Commands:
  cmd2

This is purely a visual change; the behavior will be the same as it is right now. It would help users see that certain commands are grouped together.

Versions

Python 3.11.1
click 8.1.3

[davidism]

Duplicate, has been discussed many times.

[josephlou5]

Could you link a previous issue or discussion? I couldn't find anything.

Edit: see #2115 and https://cloup.readthedocs.io/en/stable/.