From 05741f1612b965ed459fc274954605cbe421b5e8 Mon Sep 17 00:00:00 2001 From: Laurynas Keturakis Date: Fri, 21 Jul 2023 15:06:48 +0200 Subject: [PATCH 01/10] prefer use display name wherever possible --- src/lib.rs | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index b90b5cf..2c90335 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -136,7 +136,7 @@ fn write_help_markdown( writeln!( buffer, "This document contains the help content for the `{}` command-line program.\n", - command.get_name() + command.get_display_name().unwrap_or_else(|| command.get_name()) ).unwrap(); //---------------------------------- @@ -189,7 +189,12 @@ fn build_table_of_contents_markdown( // Append the name of `command` to `command_path`. let command_path = { let mut command_path = parent_command_path; - command_path.push(command.get_name().to_owned()); + command_path.push( + command + .get_display_name() + .unwrap_or_else(|| command.get_name()) + .to_owned(), + ); command_path }; @@ -277,7 +282,12 @@ fn build_command_markdown( // Append the name of `command` to `command_path`. let command_path = { let mut command_path = parent_command_path.clone(); - command_path.push(command.get_name().to_owned()); + command_path.push( + command + .get_display_name() + .unwrap_or_else(|| command.get_name()) + .to_owned(), + ); command_path }; @@ -353,7 +363,9 @@ fn build_command_markdown( writeln!( buffer, "* `{}` — {}", - subcommand.get_name(), + subcommand + .get_display_name() + .unwrap_or_else(|| subcommand.get_name()), match subcommand.get_about() { Some(about) => about.to_string(), None => String::new(), From e9239d726a9141ef1e00d3bfe891b057fe62c497 Mon Sep 17 00:00:00 2001 From: Laurynas Keturakis Date: Thu, 24 Aug 2023 19:09:35 +0200 Subject: [PATCH 02/10] refactoring + use display name then fallback to bin name then to package name Co-authored-by: Connor Gray --- src/lib.rs | 79 ++++++++++++++++++++++++++---------------- tests/test_examples.rs | 1 + 2 files changed, 51 insertions(+), 29 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 2c90335..4dec9d5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -27,6 +27,7 @@ use clap::builder::PossibleValue; pub struct MarkdownOptions { title: Option, show_footer: bool, + show_table_of_contents: bool, } impl MarkdownOptions { @@ -35,6 +36,7 @@ impl MarkdownOptions { return Self { title: None, show_footer: true, + show_table_of_contents: true, }; } @@ -51,6 +53,13 @@ impl MarkdownOptions { return self; } + + /// Whether to show the default table of contents. + pub fn show_table_of_contents(mut self, show: bool) -> Self { + self.show_table_of_contents = show; + + return self; + } } impl Default for MarkdownOptions { @@ -123,8 +132,11 @@ fn write_help_markdown( //---------------------------------- let title_name = match command.get_display_name() { - Some(display_name) => display_name.to_owned(), - None => format!("`{}`", command.get_name()), + Some(bin_name) => bin_name.to_owned(), + None => command + .get_bin_name() + .unwrap_or_else(|| command.get_name()) + .to_owned(), }; let title = match options.title { @@ -136,7 +148,7 @@ fn write_help_markdown( writeln!( buffer, "This document contains the help content for the `{}` command-line program.\n", - command.get_display_name().unwrap_or_else(|| command.get_name()) + title_name ).unwrap(); //---------------------------------- @@ -147,11 +159,14 @@ fn write_help_markdown( // build_table_of_contents_html(buffer, Vec::new(), command, 0).unwrap(); // writeln!(buffer, "").unwrap(); - writeln!(buffer, "**Command Overview:**\n").unwrap(); + if options.show_table_of_contents { + writeln!(buffer, "**Command Overview:**\n").unwrap(); - build_table_of_contents_markdown(buffer, Vec::new(), command, 0).unwrap(); + build_table_of_contents_markdown(buffer, Vec::new(), command, 0) + .unwrap(); - write!(buffer, "\n").unwrap(); + write!(buffer, "\n").unwrap(); + } //---------------------------------------- // Write the commands/subcommands sections @@ -186,15 +201,17 @@ fn build_table_of_contents_markdown( return Ok(()); } + let title_name = command + .get_display_name() + .unwrap_or_else(|| { + command.get_bin_name().unwrap_or_else(|| command.get_name()) + }) + .to_owned(); + // Append the name of `command` to `command_path`. let command_path = { let mut command_path = parent_command_path; - command_path.push( - command - .get_display_name() - .unwrap_or_else(|| command.get_name()) - .to_owned(), - ); + command_path.push(title_name); command_path }; @@ -279,15 +296,17 @@ fn build_command_markdown( return Ok(()); } + let title_name = command + .get_display_name() + .unwrap_or_else(|| { + command.get_bin_name().unwrap_or_else(|| command.get_name()) + }) + .to_owned(); + // Append the name of `command` to `command_path`. let command_path = { let mut command_path = parent_command_path.clone(); - command_path.push( - command - .get_display_name() - .unwrap_or_else(|| command.get_name()) - .to_owned(), - ); + command_path.push(title_name); command_path }; @@ -360,17 +379,19 @@ fn build_command_markdown( continue; } - writeln!( - buffer, - "* `{}` — {}", - subcommand - .get_display_name() - .unwrap_or_else(|| subcommand.get_name()), - match subcommand.get_about() { - Some(about) => about.to_string(), - None => String::new(), - } - )?; + let title_name = subcommand + .get_display_name() + .unwrap_or_else(|| { + command.get_bin_name().unwrap_or_else(|| command.get_name()) + }) + .to_owned(); + + writeln!(buffer, "* `{}` — {}", title_name, match subcommand + .get_about() + { + Some(about) => about.to_string(), + None => String::new(), + })?; } write!(buffer, "\n")?; diff --git a/tests/test_examples.rs b/tests/test_examples.rs index c6652d8..568c2bf 100644 --- a/tests/test_examples.rs +++ b/tests/test_examples.rs @@ -19,6 +19,7 @@ fn test_example_complex_app() { &MarkdownOptions::new() .title(format!("Some Custom Title for Complex App")) .show_footer(false) + .show_table_of_contents(false) ), include_str!("../docs/examples/complex-app-custom.md"), "Mismatch testing CUSTOM Markdown output" From 624f3988a946524b7cca947111c637648502ac47 Mon Sep 17 00:00:00 2001 From: Laurynas Keturakis Date: Thu, 24 Aug 2023 19:16:34 +0200 Subject: [PATCH 03/10] extract the function to a util --- src/lib.rs | 42 +++++++++++++++++------------------------- 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 4dec9d5..2d9b056 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -131,13 +131,7 @@ fn write_help_markdown( // Write the document title //---------------------------------- - let title_name = match command.get_display_name() { - Some(bin_name) => bin_name.to_owned(), - None => command - .get_bin_name() - .unwrap_or_else(|| command.get_name()) - .to_owned(), - }; + let title_name = get_canonical_name(command); let title = match options.title { Some(ref title) => title.to_owned(), @@ -188,6 +182,19 @@ fn write_help_markdown( } } +// This is a utility function to get the canonical name of a command. It's logic is +// to get the display name if it exists, otherwise get the bin name if it exists, otherwise +// get the package name. +fn get_canonical_name(command: &clap::Command) -> String { + return match command.get_display_name() { + Some(bin_name) => bin_name.to_owned(), + None => command + .get_bin_name() + .unwrap_or_else(|| command.get_name()) + .to_owned(), + }; +} + fn build_table_of_contents_markdown( buffer: &mut String, // Parent commands of `command`. @@ -201,12 +208,7 @@ fn build_table_of_contents_markdown( return Ok(()); } - let title_name = command - .get_display_name() - .unwrap_or_else(|| { - command.get_bin_name().unwrap_or_else(|| command.get_name()) - }) - .to_owned(); + let title_name = get_canonical_name(command); // Append the name of `command` to `command_path`. let command_path = { @@ -296,12 +298,7 @@ fn build_command_markdown( return Ok(()); } - let title_name = command - .get_display_name() - .unwrap_or_else(|| { - command.get_bin_name().unwrap_or_else(|| command.get_name()) - }) - .to_owned(); + let title_name = get_canonical_name(command); // Append the name of `command` to `command_path`. let command_path = { @@ -379,12 +376,7 @@ fn build_command_markdown( continue; } - let title_name = subcommand - .get_display_name() - .unwrap_or_else(|| { - command.get_bin_name().unwrap_or_else(|| command.get_name()) - }) - .to_owned(); + let title_name = get_canonical_name(subcommand); writeln!(buffer, "* `{}` — {}", title_name, match subcommand .get_about() From 8da57cc6020a89d9e1c9a0ef909328bd7c375857 Mon Sep 17 00:00:00 2001 From: Laurynas Keturakis Date: Thu, 24 Aug 2023 19:17:08 +0200 Subject: [PATCH 04/10] move util fn downstairs --- src/lib.rs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 2d9b056..f576f43 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -182,19 +182,6 @@ fn write_help_markdown( } } -// This is a utility function to get the canonical name of a command. It's logic is -// to get the display name if it exists, otherwise get the bin name if it exists, otherwise -// get the package name. -fn get_canonical_name(command: &clap::Command) -> String { - return match command.get_display_name() { - Some(bin_name) => bin_name.to_owned(), - None => command - .get_bin_name() - .unwrap_or_else(|| command.get_name()) - .to_owned(), - }; -} - fn build_table_of_contents_markdown( buffer: &mut String, // Parent commands of `command`. @@ -573,6 +560,19 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result { Ok(()) } +// This is a utility function to get the canonical name of a command. It's logic is +// to get the display name if it exists, otherwise get the bin name if it exists, otherwise +// get the package name. +fn get_canonical_name(command: &clap::Command) -> String { + return match command.get_display_name() { + Some(bin_name) => bin_name.to_owned(), + None => command + .get_bin_name() + .unwrap_or_else(|| command.get_name()) + .to_owned(), + }; +} + /// Indents non-empty lines. The output always ends with a newline. fn indent(s: &str, first: &str, rest: &str) -> String { if s.is_empty() { From b1df50aa5f09b08ed9cc8ed81d8ca857500678e0 Mon Sep 17 00:00:00 2001 From: Laurynas Keturakis Date: Fri, 25 Aug 2023 11:41:54 +0200 Subject: [PATCH 05/10] simplify the utility function Co-authored-by: Benno van den Berg --- src/lib.rs | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index f576f43..47a934b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -564,13 +564,11 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result { // to get the display name if it exists, otherwise get the bin name if it exists, otherwise // get the package name. fn get_canonical_name(command: &clap::Command) -> String { - return match command.get_display_name() { - Some(bin_name) => bin_name.to_owned(), - None => command - .get_bin_name() - .unwrap_or_else(|| command.get_name()) - .to_owned(), - }; + command + .get_display_name() + .or_else(|| command.get_bin_name()) + .map(|name| name.to_owned()) + .unwrap_or_else(|| command.get_name().to_owned()) } /// Indents non-empty lines. The output always ends with a newline. From 498311b0a6d89a198bd7995f5c86c29e13f72ef3 Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Sat, 15 Jun 2024 13:10:22 -0700 Subject: [PATCH 06/10] integration: Update new tests after rebase --- docs/examples/complex-app-custom.md | 6 ------ docs/examples/complex-app.md | 2 +- tests/test_markdown.rs | 12 ++++++------ 3 files changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/examples/complex-app-custom.md b/docs/examples/complex-app-custom.md index bdb1fa9..5611c75 100644 --- a/docs/examples/complex-app-custom.md +++ b/docs/examples/complex-app-custom.md @@ -2,12 +2,6 @@ This document contains the help content for the `complex-app` command-line program. -**Command Overview:** - -* [`complex-app`↴](#complex-app) -* [`complex-app test`↴](#complex-app-test) -* [`complex-app only-hidden-options`↴](#complex-app-only-hidden-options) - ## `complex-app` An example command-line tool diff --git a/docs/examples/complex-app.md b/docs/examples/complex-app.md index 3c10be6..5df7099 100644 --- a/docs/examples/complex-app.md +++ b/docs/examples/complex-app.md @@ -1,4 +1,4 @@ -# Command-Line Help for `complex-app` +# Command-Line Help for complex-app This document contains the help content for the `complex-app` command-line program. diff --git a/tests/test_markdown.rs b/tests/test_markdown.rs index e724775..39caeac 100644 --- a/tests/test_markdown.rs +++ b/tests/test_markdown.rs @@ -56,13 +56,13 @@ Options: "\ # Command-Line Help for my-program-display-name -This document contains the help content for the `my-program-name` command-line program. +This document contains the help content for the `my-program-display-name` command-line program. **Command Overview:** -* [`my-program-name`↴](#my-program-name) +* [`my-program-display-name`↴](#my-program-display-name) -## `my-program-name` +## `my-program-display-name` This program does things. @@ -131,13 +131,13 @@ Options: "\ # Command-Line Help for my-program-display-name -This document contains the help content for the `my-program-name` command-line program. +This document contains the help content for the `my-program-display-name` command-line program. **Command Overview:** -* [`my-program-name`↴](#my-program-name) +* [`my-program-display-name`↴](#my-program-display-name) -## `my-program-name` +## `my-program-display-name` This program does things. From 56aea55e9334709253fc9f2f48d132441c46146f Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Sat, 15 Jun 2024 13:15:28 -0700 Subject: [PATCH 07/10] integration: Move match out of write!(..) call --- src/lib.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 47a934b..8382e63 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -365,12 +365,12 @@ fn build_command_markdown( let title_name = get_canonical_name(subcommand); - writeln!(buffer, "* `{}` — {}", title_name, match subcommand - .get_about() - { + let about = match subcommand.get_about() { Some(about) => about.to_string(), None => String::new(), - })?; + }; + + writeln!(buffer, "* `{title_name}` — {about}",)?; } write!(buffer, "\n")?; From d21b18b6a3aefe0c950b4fd2252d7d59c0fb0e2b Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Sat, 15 Jun 2024 13:19:53 -0700 Subject: [PATCH 08/10] integration: Make comment into doc comment + add detail about Command.name --- src/lib.rs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 8382e63..941c4bd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -560,9 +560,14 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result { Ok(()) } -// This is a utility function to get the canonical name of a command. It's logic is -// to get the display name if it exists, otherwise get the bin name if it exists, otherwise -// get the package name. +/// Utility function to get the canonical name of a command. +/// +/// It's logic is to get the display name if it exists, otherwise get the bin +/// name if it exists, otherwise get the package name. +/// +/// Note that the default `Command.name` field of a clap command is typically +/// meant for programmatic usage as well as for display (if no `display_name` +/// override is set). fn get_canonical_name(command: &clap::Command) -> String { command .get_display_name() From 0b390b9c1708d955ebbb8fe39e3f1efb6b5f58b6 Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Sat, 15 Jun 2024 13:21:14 -0700 Subject: [PATCH 09/10] integation+bugfix: Fix regression, document title missing `..` --- docs/examples/complex-app.md | 2 +- src/lib.rs | 2 +- tests/test_markdown.rs | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/examples/complex-app.md b/docs/examples/complex-app.md index 5df7099..3c10be6 100644 --- a/docs/examples/complex-app.md +++ b/docs/examples/complex-app.md @@ -1,4 +1,4 @@ -# Command-Line Help for complex-app +# Command-Line Help for `complex-app` This document contains the help content for the `complex-app` command-line program. diff --git a/src/lib.rs b/src/lib.rs index 941c4bd..eeeb7c4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -135,7 +135,7 @@ fn write_help_markdown( let title = match options.title { Some(ref title) => title.to_owned(), - None => format!("Command-Line Help for {title_name}"), + None => format!("Command-Line Help for `{title_name}`"), }; writeln!(buffer, "# {title}\n",).unwrap(); diff --git a/tests/test_markdown.rs b/tests/test_markdown.rs index 39caeac..d44aa5a 100644 --- a/tests/test_markdown.rs +++ b/tests/test_markdown.rs @@ -54,7 +54,7 @@ Options: &MarkdownOptions::new().show_footer(false) ), "\ -# Command-Line Help for my-program-display-name +# Command-Line Help for `my-program-display-name` This document contains the help content for the `my-program-display-name` command-line program. @@ -129,7 +129,7 @@ Options: &MarkdownOptions::new().show_footer(false) ), "\ -# Command-Line Help for my-program-display-name +# Command-Line Help for `my-program-display-name` This document contains the help content for the `my-program-display-name` command-line program. From 1f12e1492d68a7939626c6015e4a8bb3938dbbfe Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Sat, 15 Jun 2024 13:30:24 -0700 Subject: [PATCH 10/10] integration: Update CHANGELOG.md --- docs/CHANGELOG.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index e692b31..5e9280e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -18,6 +18,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Contents of the command title header. - Whether to show the footer explaining the documentation was generated with `clap-markdown`. + - Whether to show the command overview table of contents. + +### Changed + +* `clap-markdown` will now respect the `Command.display_name` property, if set, + and use it in the rendered Markdown when showing the name and usage of the + command. + ([#27], + co-authored-by [@keturiosakys](https://github.com/keturiosakys) + and [@hatchan](https://github.com/hatchan)) @@ -116,6 +126,9 @@ Initial release of `clap-markdown`. [#11]: https://github.com/ConnorGray/clap-markdown/pull/11 + +[#27]: https://github.com/ConnorGray/clap-markdown/pull/27 + [unreleased]: https://github.com/ConnorGray/clap-markdown/compare/v0.1.3...HEAD [0.1.3]: https://github.com/ConnorGray/clap-markdown/compare/v0.1.2...v0.1.3