feat: add support for argument aliases in markdown output

Currently it adds the alias after the current options before the help doc. Open to other suggestions.

Author: willemneal

docs/examples/complex-app-custom.md

@@ -21,7 +21,7 @@ An example command-line tool
 
 ###### **Options:**
 
-* `-c`, `--config <FILE>` — Sets a custom config file
+* `-c`, `--config <FILE>` Aliases: `configuration` — Sets a custom config file
 * `--target <TARGET>`
 
   Default value: `local`

docs/examples/complex-app.md

@@ -27,7 +27,7 @@ An example command-line tool
 
 ###### **Options:**
 
-* `-c`, `--config <FILE>` — Sets a custom config file
+* `-c`, `--config <FILE>` Aliases: `configuration` — Sets a custom config file
 * `--target <TARGET>`
 
   Default value: `local`

docs/examples/complex_app.rs

@@ -12,7 +12,7 @@ pub struct Cli {
     name: Option<String>,
 
     /// Sets a custom config file
-    #[arg(short, long, value_name = "FILE")]
+    #[arg(short, long, value_name = "FILE", visible_alias = "configuration")]
     config: Option<PathBuf>,
 
     #[arg(long, default_value = "local")]

src/lib.rs

@@ -459,9 +459,9 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
         },
         (None, Some(long)) => {
             if arg.get_action().takes_values() {
-                write!(buffer, "`--{} <{value_name}>`", long)?
+                write!(buffer, "`--{long} <{value_name}>`")?
             } else {
-                write!(buffer, "`--{}`", long)?
+                write!(buffer, "`--{long}`")?
             }
         },
         (None, None) => {
@@ -471,6 +471,18 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
         },
     }
 
+    if let Some(aliases) = arg.get_visible_aliases() {
+        if !aliases.is_empty() {
+            write!(buffer, " Aliases: ")?;
+            for (i, alias) in aliases.into_iter().enumerate() {
+                if i > 0 {
+                    write!(buffer, ", ")?;
+                }
+                write!(buffer, "`{alias}`")?;
+            }
+        }
+    }
+
     if let Some(help) = arg.get_long_help() {
         // TODO: Parse formatting in the string
         buffer.push_str(&indent(&help.to_string(), " — ", "   "))