Subcommand headings do not work

[milesj]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Rust Version

rustc 1.58.0 (02072b482 2022-01-11)

Clap Version

3.1.0

Minimal reproducible code

Example PR where I'm testing: moonrepo/moon#51

That being said, I've tried all of these patterns to add headings to subcommands with no luck.

#[derive(Subcommand)]
pub enum SubCommands {
    #[clap(name = "cmd1", help_heading = "Group")]
    Cmd1,

    #[clap(name = "cmd2", next_help_heading = "Group")]
    Cmd2,

    #[clap(name = "cmd3", subcommand_help_heading = "Group")]
    Cmd3,
}

Steps to reproduce the bug with the above code

Just apply the subcommands to an app/parser.

#[derive(Parser)]
pub struct App {
    #[clap(subcommand)]
    pub command: SubCommands,
}

Actual Behaviour

Instead of altering the help menu on the "main" entry point where the subcommands are listed (moon --help), these 3 patterns above seemed to alter the help menu of the args in the command itself (moon bin --help, which seemed wrong, since those args have their own heading settings.

For example, this is the output I get for my command (notice the "Group").

moon-bin 0.1.0
Return an absolute path to a tool's binary within the toolchain. If a tool has not been configured or installed, this will return a non-zero exit code with no value.

USAGE:
    moon bin <TOOL>

OPTIONS:
    -h, --help
            Print help information

    -V, --version
            Print version information

Group:
    <TOOL>
            The tool to query

            [possible values: node, npm, pnpm, yarn]

Expected Behaviour

All 3 of those patterns above did not alter the help menu for the "main" entry point (moon --help). For example, this is my current CLI output.

MOON 0.1.0
Take your monorepo to the moon!

USAGE:
    moon [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -h, --help                     Print help information
    -L, --log-level <LOG_LEVEL>    Lowest log level to output [possible values: off, error, warn, info, debug, trace]
    -V, --version                  Print version information

SUBCOMMANDS:
    bin              Return an absolute path to a tool's binary within the toolchain.
    project          Display information about a single project.
    project-graph    Display a graph of projects in DOT format.
    run              Run a project task and all its dependent tasks.
    setup            Setup the environment by installing all tools.
    teardown         Teardown the environment by uninstalling all tools and deleting temp files.

What i'm looking for is something like this:

MOON 0.1.0
Take your monorepo to the moon!

USAGE:
    moon [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -h, --help                     Print help information
    -L, --log-level <LOG_LEVEL>    Lowest log level to output [possible values: off, error, warn, info, debug, trace]
    -V, --version                  Print version information

ENVIRONMENT COMMANDS:
    bin              Return an absolute path to a tool's binary within the toolchain.
    setup            Setup the environment by installing all tools.
    teardown         Teardown the environment by uninstalling all tools and deleting temp files.

PROJECT COMMANDS:
    project          Display information about a single project.
    project-graph    Display a graph of projects in DOT format.
    run              Run a project task and all its dependent tasks.

Additional Context

No response

Debug Output

No response

[epage]

subcommand_help_heading is the only one that applies to subcommands and it applies to all subcommands. See our multicall-busybox example for what the output looks like and how to use it. That example is only done with the builder API but the principles are the same.

#1553 is our issue for supporting multiple subcommand help headings.

Closing this out in favor of #1553

[milesj]

Thank you!

[epage]

Also, #1553 is marked for the 4.0 milestone and our renaming of help_heading to next_help_heading was part of the prep work for it.