[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 <[email protected]>

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:**
+
+* `<NAME>` — Optional name to operate on
+
+   Longer description
+
+###### **Options:**
+
+* `-c`, `--config <FILE>` — Sets a custom config file
+* `--target <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`
+
+
+

src/lib.rs

@@ -12,23 +12,82 @@ 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<String>,
+    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<C: clap::CommandFactory>() -> String {
     let command = C::command();
 
     help_markdown_command(&command)
 }
 
+/// Format the help information for `command` as Markdown, with custom options.
+pub fn help_markdown_custom<C: clap::CommandFactory>(
+    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<C: clap::CommandFactory>() {
 
     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#"<hr/>
+    if options.show_footer {
+        write!(buffer, r#"<hr/>
 
 <small><i>
     This document was generated automatically by
     <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
 </i></small>
 "#).unwrap();
+    }
 }
 
 fn build_table_of_contents_markdown(

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::<complex_app::Cli>(),
         include_str!("../docs/examples/complex-app.md")
     );
+
+    assert_eq!(
+        clap_markdown::help_markdown_custom::<complex_app::Cli>(
+            &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"
+    );
 }