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 688a648..374ffdd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,13 +12,57 @@ mod test_readme { #![doc = include_str!("../README.md")] } -use std::{ - default, - fmt::{self, Write}, -}; +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(); @@ -27,8 +71,8 @@ pub fn help_markdown() -> String { } /// Format the help information for `command` as Markdown, with custom options. -pub fn custom_help_markdown( - options: MarkdownOptions, +pub fn help_markdown_custom( + options: &MarkdownOptions, ) -> String { let command = C::command(); @@ -43,7 +87,7 @@ pub fn custom_help_markdown( pub fn help_markdown_command(command: &clap::Command) -> String { let mut buffer = String::with_capacity(100); - write_help_markdown(&mut buffer, command, default::Default::default()); + write_help_markdown(&mut buffer, command, &Default::default()); buffer } @@ -60,21 +104,15 @@ pub fn print_help_markdown() { let mut buffer = String::with_capacity(100); - write_help_markdown(&mut buffer, &command, default::Default::default()); + write_help_markdown(&mut buffer, &command, &Default::default()); println!("{}", buffer); } -#[derive(Default)] -pub struct MarkdownOptions { - pub title: Option, - pub hide_footer: bool, -} - fn write_help_markdown( buffer: &mut String, command: &clap::Command, - options: MarkdownOptions, + options: &MarkdownOptions, ) { //---------------------------------- // Write the document title @@ -120,7 +158,7 @@ fn write_help_markdown( //----------------- // Write the footer //----------------- - if !options.hide_footer { + if options.show_footer { write!(buffer, r#"
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" + ); }