feat(output): Support subcommand help headings

- 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/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]