feat: Add subcommand custom headings

- add tests for subcommand headings feature
- include tests for single and multiple help headers
- add test for hiding commands header
- add test for mixed standard and custom headers
- add support for subcommand help headings
- display subcommands under their respective headings in help output
- only display heading if subcommand has `help_heading` set

Author: gortavoher

clap_builder/src/builder/command.rs

@@ -104,6 +104,7 @@ pub struct Command {
     current_disp_ord: Option<usize>,
     subcommand_value_name: Option<Str>,
     subcommand_heading: Option<Str>,
+    help_heading: Option<Option<Str>>,
     external_value_parser: Option<super::ValueParser>,
     long_help_exists: bool,
     deferred: Option<fn(Command) -> Command>,
@@ -3701,6 +3702,82 @@ impl Command {
         self.subcommand_heading = heading.into_resettable().into_option();
         self
     }
+
+    /// Set a custom help heading
+    ///
+    /// To place the `help` subcommand under a custom heading amend the default
+    /// heading using [`Command::subcommand_help_heading`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg};
+    ///   Command::new("myprog")
+    ///     .version("2.6")
+    ///     .subcommand(
+    ///        Command::new("show")
+    ///          .about("Help for show")
+    ///     )
+    ///     .print_help()
+    /// # ;
+    /// ```
+    ///
+    /// will produce
+    ///
+    /// ```text
+    /// myprog
+    ///
+    /// Usage: myprog [COMMAND]
+    ///
+    /// Commands:
+    ///     help    Print this message or the help of the given subcommand(s)
+    ///     show    Help for show
+    ///
+    /// Options:
+    ///     -h, --help       Print help
+    ///     -V, --version    Print version
+    /// ```
+    ///
+    /// but usage of `help_heading`
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg};
+    ///   Command::new("myprog")
+    ///     .version("2.6")
+    ///     .subcommand(
+    ///         Command::new("show")
+    ///             .about("Help for show")
+    ///             .help_heading("Custom heading"),
+    ///     )
+    ///     .print_help()
+    /// # ;
+    /// ```
+    ///
+    /// will produce
+    ///
+    /// ```text
+    /// myprog
+    ///
+    /// Usage: myprog [COMMAND]
+    ///
+    /// Commands:
+    ///     help    Print this message or the help of the given subcommand(s)
+    ///
+    /// Custom heading:
+    ///     show    Help for show
+    ///
+    /// Options:
+    ///     -h, --help       Print help
+    ///     -V, --version    Print version
+    /// ```
+    #[inline]
+    #[must_use]
+    pub fn help_heading(mut self, heading: impl IntoResettable<Str>) -> Self {
+        self.help_heading = Some(heading.into_resettable().into_option());
+        self
+    }
 }
 
 /// # Reflection
@@ -3940,6 +4017,15 @@ impl Command {
         self.subcommand_heading.as_deref()
     }
 
+    /// Get the help heading specified for this command, if any
+    #[inline]
+    pub fn get_help_heading(&self) -> Option<&str> {
+        self.help_heading
+            .as_ref()
+            .map(|s| s.as_deref())
+            .unwrap_or_default()
+    }
+
     /// Returns the subcommand value name.
     #[inline]
     pub fn get_subcommand_value_name(&self) -> Option<&str> {
@@ -4230,6 +4316,11 @@ impl Command {
         self.is_set(AppSettings::Hidden)
     }
 
+    /// Report whether [`Command::help_heading`] is set
+    pub fn is_help_heading_set(&self) -> bool {
+        self.help_heading.is_some()
+    }
+
     /// Report whether [`Command::subcommand_required`] is set
     pub fn is_subcommand_required_set(&self) -> bool {
         self.is_set(AppSettings::SubcommandRequired)
@@ -5218,6 +5309,7 @@ impl Default for Command {
             current_disp_ord: Some(0),
             subcommand_value_name: Default::default(),
             subcommand_heading: Default::default(),
+            help_heading: Default::default(),
             external_value_parser: Default::default(),
             long_help_exists: false,
             deferred: None,

clap_builder/src/output/help_template.rs

@@ -963,12 +963,39 @@ impl HelpTemplate<'_, '_> {
 
         let next_line_help = self.will_subcommands_wrap(cmd.get_subcommands(), longest);
 
-        for (i, (sc_str, sc)) in ord_v.into_iter().enumerate() {
+        // First for the commands that don't have a heading
+        for (i, (sc_str, sc)) in ord_v
+            .clone()
+            .into_iter()
+            .filter(|item| !should_show_help_heading(item.1))
+            .enumerate()
+        {
+            debug!("Processing without heading {}", sc.get_name());
             if 0 < i {
                 self.writer.push_str("\n");
             }
             self.write_subcommand(sc_str.1, sc, next_line_help, longest);
         }
+
+        let header = &self.styles.get_header();
+        let mut current_heading = "";
+
+        // Then for the commands that do have a heading
+        for (sc_str, sc) in ord_v
+            .into_iter()
+            .filter(|item| should_show_help_heading(item.1))
+        {
+            debug!("Processing with heading {}", sc.get_name());
+            self.writer.push_str("\n");
+            if sc.get_help_heading().unwrap() != current_heading {
+                current_heading = sc.get_help_heading().unwrap();
+                debug!("Heading changed; print new heading {}.", current_heading);
+                self.writer.push_str("\n");
+                let _ = write!(self.writer, "{header}{current_heading}:{header:#}\n",);
+            }
+
+            self.write_subcommand(sc_str.1, sc, next_line_help, longest);
+        }
     }
 
     /// Will use next line help on writing subcommands.
@@ -1142,6 +1169,10 @@ fn should_show_subcommand(subcommand: &Command) -> bool {
     !subcommand.is_hide_set()
 }
 
+fn should_show_help_heading(subcommand: &Command) -> bool {
+    subcommand.is_help_heading_set()
+}
+
 #[cfg(test)]
 mod test {
     #[test]

tests/builder/subcommands.rs

@@ -635,3 +635,184 @@ fn duplicate_subcommand_alias() {
         .subcommand(Command::new("unique").alias("repeat"))
         .build();
 }
+
+#[test]
+fn test_help_header() {
+    static VISIBLE_ALIAS_HELP: &str = "\
+Usage: clap-test [COMMAND]
+
+Commands:
+  help  Print this message or the help of the given subcommand(s)
+
+Test commands:
+  test  Some help
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+";
+    
+    let cmd = Command::new("clap-test")
+    .version("2.6")
+    .subcommand(
+        Command::new("test")
+        .about("Some help")
+        .help_heading("Test commands"),
+    );
+    utils::assert_output(cmd, "clap-test --help", VISIBLE_ALIAS_HELP, false);
+}
+
+#[test]
+fn test_help_header_multiple_help_headers() {
+    static VISIBLE_ALIAS_HELP: &str = "\
+Usage: clap-test [COMMAND]
+
+Commands:
+  help   Print this message or the help of the given subcommand(s)
+
+Test Commands 1:
+  test1  Some help
+
+Test Commands 2:
+  test2  Some help
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+";
+
+    let cmd = Command::new("clap-test")
+        .version("2.6")
+        .subcommand(
+            Command::new("test1")
+                .about("Some help")
+                .help_heading("Test Commands 1"),
+        )
+        .subcommand(
+            Command::new("test2")
+                .about("Some help")
+                .help_heading("Test Commands 2"),
+        );
+
+    utils::assert_output(cmd, "clap-test --help", VISIBLE_ALIAS_HELP, false);
+}
+
+#[test]
+fn test_help_header_hide_commands_header() {
+    static VISIBLE_ALIAS_HELP: &str = "\
+Usage: clap-test [COMMAND]
+
+Test commands:
+  test  Some help
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+";
+
+    let cmd = Command::new("clap-test")
+        .version("2.6")
+        .disable_help_subcommand(true)
+        .subcommand_help_heading("Test commands")
+        .subcommand(Command::new("test").about("Some help"));
+    utils::assert_output(cmd, "clap-test --help", VISIBLE_ALIAS_HELP, false);
+}
+
+#[test]
+fn test_multiple_commands_mixed_standard_and_custom_headers() {
+    static VISIBLE_ALIAS_HELP: &str = "\
+Usage: clap-test [COMMAND]
+
+Help Section:
+  help      Print this message or the help of the given subcommand(s)
+
+Commands:
+  def_cmd1  First command under default command heading
+  def_cmd2  Second command under default command heading
+  def_cmd3  Third command under default command heading
+  def_cmd4  Fourth command under default command heading
+
+First Custom:
+  ch1_cmd1  First command under first custom command heading
+  ch1_cmd2  Second command under first custom command heading
+  ch1_cmd3  Third command under first custom command heading
+  ch1_cmd4  Fourth command under first custom command heading
+
+Second Custom:
+  ch2_cmd1  First command under second custom command heading
+  ch2_cmd2  Second command under second custom command heading
+  ch2_cmd3  Third command under second custom command heading
+  ch2_cmd4  Fourth command under second custom command heading
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+";
+
+    let cmd = Command::new("clap-test")
+        .version("2.6")
+        .subcommand_help_heading("Help Section")
+        .subcommand(
+            Command::new("def_cmd1")
+                .about("First command under default command heading")
+                .help_heading("Commands"),
+        )
+        .subcommand(
+            Command::new("def_cmd2")
+                .about("Second command under default command heading")
+                .help_heading("Commands"),
+        )
+        .subcommand(
+            Command::new("def_cmd3")
+                .about("Third command under default command heading")
+                .help_heading("Commands"),
+        )
+        .subcommand(
+            Command::new("def_cmd4")
+                .about("Fourth command under default command heading")
+                .help_heading("Commands"),
+        )
+        .subcommand(
+            Command::new("ch1_cmd1")
+                .about("First command under first custom command heading")
+                .help_heading("First Custom"),
+        )
+        .subcommand(
+            Command::new("ch1_cmd2")
+                .about("Second command under first custom command heading")
+                .help_heading("First Custom"),
+        )
+        .subcommand(
+            Command::new("ch1_cmd3")
+                .about("Third command under first custom command heading")
+                .help_heading("First Custom"),
+        )
+        .subcommand(
+            Command::new("ch1_cmd4")
+                .about("Fourth command under first custom command heading")
+                .help_heading("First Custom"),
+        )
+        .subcommand(
+            Command::new("ch2_cmd1")
+                .about("First command under second custom command heading")
+                .help_heading("Second Custom"),
+        )
+        .subcommand(
+            Command::new("ch2_cmd2")
+                .about("Second command under second custom command heading")
+                .help_heading("Second Custom"),
+        )
+        .subcommand(
+            Command::new("ch2_cmd3")
+                .about("Third command under second custom command heading")
+                .help_heading("Second Custom"),
+        )
+        .subcommand(
+            Command::new("ch2_cmd4")
+                .about("Fourth command under second custom command heading")
+                .help_heading("Second Custom"),
+        );
+
+    utils::assert_output(cmd, "clap-test --help", VISIBLE_ALIAS_HELP, false);
+}
+