feature: Print long help text for options (#23)

feature: Print long help text for options

Fixes #20

I wrote my own `indent` function to avoid introducing any new dependencies
(`indent` or `textwrap` crate).

---------

Co-authored-by: Connor Gray <[email protected]>

docs/examples/complex-app.md

@@ -23,6 +23,8 @@ An example command-line tool
 
 * `<NAME>` — Optional name to operate on
 
+   Longer description
+
 ###### **Options:**
 
 * `-c`, `--config <FILE>` — Sets a custom config file
@@ -37,6 +39,8 @@ An example command-line tool
 
 * `-d`, `--debug` — Turn debugging information on
 
+   Repeat this option to see more and more debug information.
+
 
 
 ## `complex-app test`

docs/examples/complex_app.rs

@@ -7,6 +7,8 @@ use clap::{Parser, Subcommand};
 #[command(name = "complex-app")]
 pub struct Cli {
     /// Optional name to operate on
+    ///
+    /// Longer description
     name: Option<String>,
 
     /// Sets a custom config file
@@ -17,6 +19,8 @@ pub struct Cli {
     target: Target,
 
     /// Turn debugging information on
+    ///
+    /// Repeat this option to see more and more debug information.
     #[arg(short, long, action = clap::ArgAction::Count)]
     debug: u8,
 

src/lib.rs

@@ -379,8 +379,11 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
         },
     }
 
-    if let Some(help) = arg.get_help() {
-        writeln!(buffer, " — {help}")?;
+    if let Some(help) = arg.get_long_help() {
+        // TODO: Parse formatting in the string
+        buffer.push_str(&indent(&help.to_string(), " — ", "   "))
+    } else if let Some(short_help) = arg.get_help() {
+        writeln!(buffer, " — {short_help}")?;
     } else {
         writeln!(buffer)?;
     }
@@ -464,3 +467,44 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
 
     Ok(())
 }
+
+/// Indents non-empty lines. The output always ends with a newline.
+fn indent(s: &str, first: &str, rest: &str) -> String {
+    if s.is_empty() {
+        // For consistency. It's easiest to always add a newline at the end, and
+        // there's little reason not to.
+        return "\n".to_string();
+    }
+    let mut result = String::new();
+    let mut first_line = true;
+
+    for line in s.lines() {
+        if !line.is_empty() {
+            result.push_str(if first_line { first } else { rest });
+            result.push_str(line);
+            first_line = false;
+        }
+        result.push('\n');
+    }
+    result
+}
+
+#[cfg(test)]
+mod test {
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn test_indent() {
+        use super::indent;
+        assert_eq!(
+            &indent("Header\n\nMore info", "___", "~~~~"),
+            "___Header\n\n~~~~More info\n"
+        );
+        assert_eq!(
+            &indent("Header\n\nMore info\n", "___", "~~~~"),
+            &indent("Header\n\nMore info", "___", "~~~~"),
+        );
+        assert_eq!(&indent("", "___", "~~~~"), "\n");
+        assert_eq!(&indent("\n", "___", "~~~~"), "\n");
+    }
+}