From e13c09d21839514cd6f32168c0cb7817ab983169 Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Fri, 14 Jun 2024 23:09:37 -0700 Subject: [PATCH] [PR Integration] feat: add options for controlling formatting #17 (#25) * feat: add option to override title * feat: add option to hide footer * integration: Polish MarkdownOptions type + add test for custom options behavior --------- Co-authored-by: Morgante Pell --- docs/examples/complex-app-custom.md | 65 +++++++++++++++++++++++ src/lib.rs | 82 ++++++++++++++++++++++++++--- tests/test_examples.rs | 11 ++++ 3 files changed, 151 insertions(+), 7 deletions(-) create mode 100644 docs/examples/complex-app-custom.md diff --git a/docs/examples/complex-app-custom.md b/docs/examples/complex-app-custom.md new file mode 100644 index 0000000..bdb1fa9 --- /dev/null +++ b/docs/examples/complex-app-custom.md @@ -0,0 +1,65 @@ +# Some Custom Title for Complex App + +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 + +**Usage:** `complex-app [OPTIONS] [NAME] [COMMAND]` + +###### **Subcommands:** + +* `test` — does testing things +* `only-hidden-options` — Demo that `Options` is not printed if all options are hidden + +###### **Arguments:** + +* `` — Optional name to operate on + + Longer description + +###### **Options:** + +* `-c`, `--config ` — Sets a custom config file +* `--target ` + + Default value: `local` + + Possible values: + - `local`: + Do the operation locally + - `remote` + +* `-d`, `--debug` — Turn debugging information on + + Repeat this option to see more and more debug information. + + + +## `complex-app test` + +does testing things + +**Usage:** `complex-app test [OPTIONS]` + +###### **Options:** + +* `-l`, `--list` — lists test values + + + +## `complex-app only-hidden-options` + +Demo that `Options` is not printed if all options are hidden + +**Usage:** `complex-app only-hidden-options` + + + diff --git a/src/lib.rs b/src/lib.rs index b4a1a2d..374ffdd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,11 +12,57 @@ mod test_readme { #![doc = include_str!("../README.md")] } - use std::fmt::{self, Write}; use clap::builder::PossibleValue; +//====================================== +// Public API types +//====================================== + +/// Options to customize the structure of the output Markdown document. +/// +/// Used with [`help_markdown_custom()`]. +#[non_exhaustive] +pub struct MarkdownOptions { + title: Option, + show_footer: bool, +} + +impl MarkdownOptions { + /// Construct a default instance of `MarkdownOptions`. + pub fn new() -> Self { + return Self { + title: None, + show_footer: true, + }; + } + + /// Set a custom title to use in the generated document. + pub fn title(mut self, title: String) -> Self { + self.title = Some(title); + + return self; + } + + /// Whether to show the default footer advertising `clap-markdown`. + pub fn show_footer(mut self, show: bool) -> Self { + self.show_footer = show; + + return self; + } +} + +impl Default for MarkdownOptions { + fn default() -> Self { + return Self::new(); + } +} + +//====================================== +// Public API functions +//====================================== + /// Format the help information for `command` as Markdown. pub fn help_markdown() -> String { let command = C::command(); @@ -24,11 +70,24 @@ pub fn help_markdown() -> String { help_markdown_command(&command) } +/// Format the help information for `command` as Markdown, with custom options. +pub fn help_markdown_custom( + options: &MarkdownOptions, +) -> String { + let command = C::command(); + + let mut buffer = String::with_capacity(100); + + write_help_markdown(&mut buffer, &command, options); + + buffer +} + /// Format the help information for `command` as Markdown. pub fn help_markdown_command(command: &clap::Command) -> String { let mut buffer = String::with_capacity(100); - write_help_markdown(&mut buffer, command); + write_help_markdown(&mut buffer, command, &Default::default()); buffer } @@ -45,12 +104,16 @@ pub fn print_help_markdown() { let mut buffer = String::with_capacity(100); - write_help_markdown(&mut buffer, &command); + write_help_markdown(&mut buffer, &command, &Default::default()); println!("{}", buffer); } -fn write_help_markdown(buffer: &mut String, command: &clap::Command) { +fn write_help_markdown( + buffer: &mut String, + command: &clap::Command, + options: &MarkdownOptions, +) { //---------------------------------- // Write the document title //---------------------------------- @@ -60,7 +123,11 @@ fn write_help_markdown(buffer: &mut String, command: &clap::Command) { None => format!("`{}`", command.get_name()), }; - writeln!(buffer, "# Command-Line Help for {title_name}\n").unwrap(); + let title = match options.title { + Some(ref title) => title.to_owned(), + None => format!("Command-Line Help for {title_name}"), + }; + writeln!(buffer, "# {title}\n",).unwrap(); writeln!( buffer, @@ -91,14 +158,15 @@ fn write_help_markdown(buffer: &mut String, command: &clap::Command) { //----------------- // Write the footer //----------------- - - write!(buffer, r#"
+ if options.show_footer { + write!(buffer, r#"
This document was generated automatically by clap-markdown. "#).unwrap(); + } } fn build_table_of_contents_markdown( diff --git a/tests/test_examples.rs b/tests/test_examples.rs index 0b3fdaa..a6bf271 100644 --- a/tests/test_examples.rs +++ b/tests/test_examples.rs @@ -1,3 +1,4 @@ +use clap_markdown::MarkdownOptions; use pretty_assertions::assert_eq; #[test] @@ -10,4 +11,14 @@ fn test_example_complex_app() { clap_markdown::help_markdown::(), include_str!("../docs/examples/complex-app.md") ); + + assert_eq!( + clap_markdown::help_markdown_custom::( + &MarkdownOptions::new() + .title(format!("Some Custom Title for Complex App")) + .show_footer(false) + ), + include_str!("../docs/examples/complex-app-custom.md"), + "Mismatch testing CUSTOM Markdown output" + ); }