CI - ci self-docs includes value names (#5152)

# Description of Changes

the `README.md` (generated by `cargo ci self-docs`) now properly
includes the value names passed to args.

This change was made by AI.

# API and ABI breaking changes

None. CI only.

# Expected complexity level and risk

1

# Testing
CI, including the docs check, passes

Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>

Author: bfops

tools/ci/README.md

@@ -19,7 +19,7 @@ Usage: cargo ci [OPTIONS] [COMMAND]
 
 **Options:**
 
-- `--skip`: Skip specified subcommands when running all
+- `--skip <SKIP>`: Skip specified subcommands when running all
 
 When no subcommand is specified, all subcommands are run in sequence. This option allows specifying subcommands to skip when running all. For example, to skip the `unreal-tests` subcommand, use `--skip unreal-tests`.
 
@@ -98,12 +98,12 @@ Usage: smoketests [OPTIONS] [ARGS]... [COMMAND]
 
 **Options:**
 
-- `--server`: Run tests against a remote server instead of spawning local servers.
+- `--server <SERVER>`: Run tests against a remote server instead of spawning local servers.
 
 When specified, tests will connect to the given URL instead of starting local server instances. Tests that require local server control (like restart tests) will be skipped.
 
-- `--dotnet`: 
-- `args`: Additional arguments to pass to the test runner
+- `--dotnet <DOTNET>`:
+- `args <ARGS>`: Additional arguments to pass to the test runner
 - `--help`: Print help (see a summary with '-h')
 
 #### `prepare`
@@ -141,7 +141,7 @@ Usage: help [COMMAND]...
 
 **Options:**
 
-- `subcommand`: Print help for the subcommand(s)
+- `subcommand <COMMAND>`: Print help for the subcommand(s)
 
 ### `keynote-bench`
 
@@ -171,7 +171,7 @@ Usage: update-flow [OPTIONS]
 
 **Options:**
 
-- `--target`: Target triple to build for, by default the current target. Used by github workflows to check the update flow on multiple platforms.
+- `--target <TARGET>`: Target triple to build for, by default the current target. Used by github workflows to check the update flow on multiple platforms.
 - `--github-token-auth`: Whether to enable github token authentication feature when building the update binary. By default this is disabled.
 - `--help`: Print help (see a summary with '-h')
 
@@ -184,7 +184,7 @@ Usage: cli-docs [OPTIONS]
 
 **Options:**
 
-- `--spacetime-path`: specify a custom path to the SpacetimeDB repository root (where the main Cargo.toml is located)
+- `--spacetime-path <SPACETIME_PATH>`: specify a custom path to the SpacetimeDB repository root (where the main Cargo.toml is located)
 - `--help`: Print help (see a summary with '-h')
 
 ### `self-docs`
@@ -263,7 +263,7 @@ Usage: help [COMMAND]...
 
 **Options:**
 
-- `subcommand`: Print help for the subcommand(s)
+- `subcommand <COMMAND>`: Print help for the subcommand(s)
 
 
 ---

tools/ci/src/ci_docs.rs

@@ -41,11 +41,16 @@ fn generate_markdown(cmd: &mut Command, heading_level: usize) -> String {
 
     let mut options = String::new();
     for arg in cmd.get_arguments() {
-        let names = arg
+        let mut names = arg
             .get_long()
             .map(|l| format!("--{}", l))
             .or_else(|| arg.get_short().map(|s| format!("-{}", s)))
             .unwrap_or_else(|| arg.get_id().to_string());
+        if let Some(value_names) = arg.get_value_names().filter(|_| arg.get_action().takes_values()) {
+            for value_name in value_names {
+                names.push_str(&format!(" <{value_name}>"));
+            }
+        }
         let help = arg
             .get_long_help()
             .or_else(|| arg.get_help())
@@ -54,12 +59,16 @@ fn generate_markdown(cmd: &mut Command, heading_level: usize) -> String {
                 eprintln!("Warning: argument `{}` is missing help text", arg.get_id());
                 "".to_string()
             });
-        options.push_str(&format!(
-            "- `{}`: {}\n{}",
-            names,
-            help,
-            if help.lines().count() > 1 { "\n" } else { "" }
-        ));
+        if help.is_empty() {
+            options.push_str(&format!("- `{names}`:\n"));
+        } else {
+            options.push_str(&format!(
+                "- `{}`: {}\n{}",
+                names,
+                help,
+                if help.lines().count() > 1 { "\n" } else { "" }
+            ));
+        }
     }
 
     if !options.is_empty() {