feat: add custom help headings

- Allow setting custom help headings for subcommands to group them.
- Add `help_heading` method to `Command` to set the custom heading.
- Update help template to display subcommands under their headings.
- Add `get_help_heading` method to retrieve the custom heading.
- Add `is_help_heading_set` method to check a custom heading is set.
- Update tests to verify display of subcommands with custom headings.

Author: gortavoher

clap_builder/src/builder/command.rs

@@ -3703,23 +3703,81 @@ impl Command {
         self
     }
 
-
-    /// Set a custom help heading
+    /// Set a custom help heading for the command
+    ///
+    /// 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
     }
-
-    /// Get the help heading specified for this argument, if any
-    #[inline]
-    pub fn get_help_heading(&self) -> Option<&str> {
-        self.help_heading
-            .as_ref()
-            .map(|s| s.as_deref())
-            .unwrap_or_default()
-    }
 }
 
 /// # Reflection
@@ -3959,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> {
@@ -4253,7 +4320,7 @@ impl Command {
     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)

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

@@ -639,19 +639,18 @@ fn duplicate_subcommand_alias() {
 #[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
-    ";
-    
+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(