From 8a60dbd629e3e0e3663f674aad3e942f03f7dcac Mon Sep 17 00:00:00 2001 From: Connor Gray Date: Sat, 15 Jun 2024 12:19:34 -0700 Subject: [PATCH] test: More exhaustively test current name/bin_name/display_name handling behavior (#28) --- Cargo.toml | 2 +- docs/CHANGELOG.md | 11 +++ src/lib.rs | 16 +++-- tests/test_examples.rs | 2 + tests/test_markdown.rs | 156 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 180 insertions(+), 7 deletions(-) create mode 100644 tests/test_markdown.rs diff --git a/Cargo.toml b/Cargo.toml index c32498f..7853a6b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,6 +16,6 @@ categories = ["command-line-interface", "command-line-utilities", "development-t clap = "4.*.*" [dev-dependencies] -clap = { version = "4.*.*", features = ["derive"] } +clap = { version = "4.4.0", features = ["derive"] } pretty_assertions = "1.3.0" diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index dd3544a..e692b31 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +* Added `help_markdown_custom()` and `help_markdown_command_custom()`, for + customizing the built Markdown. + + Supported customization options include: + + - Contents of the command title header. + - Whether to show the footer explaining the documentation was generated with + `clap-markdown`. + ## [0.1.3] - 2022-12-28 diff --git a/src/lib.rs b/src/lib.rs index 1c4c095..b90b5cf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -76,18 +76,22 @@ pub fn help_markdown_custom( ) -> String { let command = C::command(); - let mut buffer = String::with_capacity(100); - - write_help_markdown(&mut buffer, &command, options); - - buffer + return help_markdown_command_custom(&command, options); } /// Format the help information for `command` as Markdown. pub fn help_markdown_command(command: &clap::Command) -> String { + return help_markdown_command_custom(command, &Default::default()); +} + +/// Format the help information for `command` as Markdown, with custom options. +pub fn help_markdown_command_custom( + command: &clap::Command, + options: &MarkdownOptions, +) -> String { let mut buffer = String::with_capacity(100); - write_help_markdown(&mut buffer, command, &Default::default()); + write_help_markdown(&mut buffer, &command, options); buffer } diff --git a/tests/test_examples.rs b/tests/test_examples.rs index a6bf271..c6652d8 100644 --- a/tests/test_examples.rs +++ b/tests/test_examples.rs @@ -1,6 +1,8 @@ use clap_markdown::MarkdownOptions; use pretty_assertions::assert_eq; +/// Tests that the `complex-app` example featured in the README.md is +/// up-to-date. #[test] fn test_example_complex_app() { mod complex_app { diff --git a/tests/test_markdown.rs b/tests/test_markdown.rs new file mode 100644 index 0000000..e724775 --- /dev/null +++ b/tests/test_markdown.rs @@ -0,0 +1,156 @@ +use clap::{Arg, Command}; +use clap_markdown::{help_markdown_command_custom, MarkdownOptions}; + +use pretty_assertions::assert_eq; + +/// Test behavior for an app that defines a: +/// +/// * `name` +/// * `display_name` +/// +/// but no custom `bin_name`. +#[test] +fn test_title_behavior_for_name_and_display_name_app() { + let mut app = Command::new("my-program-name") + // Note: Intentionally not setting custom bin name. + // .bin_name("my-program-bin-name") + .display_name("my-program-display-name") + .version("1.2.3") + .about("This program does things.") + .arg(Arg::new("foo").short('f')); + let () = app.build(); + + //------------------------------------------------------------------- + // Test the native behavior of `clap`, in terms of whether it prefers + // the `name`, `bin_name`, and `display_name` properties are used. + //------------------------------------------------------------------- + + assert_eq!( + app.render_long_help().to_string(), + "\ +This program does things. + +Usage: my-program-name [OPTIONS] + +Options: + -f + + + -h, --help + Print help + + -V, --version + Print version +" + ); + + //------------------------------------------------------- + // Test how clap-markdown handles the various name fields + //------------------------------------------------------- + + assert_eq!( + help_markdown_command_custom( + &app, + &MarkdownOptions::new().show_footer(false) + ), + "\ +# Command-Line Help for my-program-display-name + +This document contains the help content for the `my-program-name` command-line program. + +**Command Overview:** + +* [`my-program-name`↴](#my-program-name) + +## `my-program-name` + +This program does things. + +**Usage:** `my-program-name [OPTIONS]` + +###### **Options:** + +* `-f ` +* `-h`, `--help` — Print help +* `-V`, `--version` — Print version + + + +" + ); +} + +/// Test behavior for an app that defines a: +/// +/// * `name` +/// * `bin_name` +/// * `display_name` +#[test] +fn test_title_behavior_for_name_bin_name_and_display_name_app() { + let mut app = Command::new("my-program-name") + .bin_name("my-program-bin-name") + .display_name("my-program-display-name") + .version("1.2.3") + .about("This program does things.") + .arg(Arg::new("foo").short('f')); + let () = app.build(); + + //------------------------------------------------------------------- + // Test the native behavior of `clap`, in terms of whether it prefers + // the `name`, `bin_name`, and `display_name` properties are used. + //------------------------------------------------------------------- + + assert_eq!( + app.render_long_help().to_string(), + "\ +This program does things. + +Usage: my-program-bin-name [OPTIONS] + +Options: + -f + + + -h, --help + Print help + + -V, --version + Print version +" + ); + + //------------------------------------------------------- + // Test how clap-markdown handles the various name fields + //------------------------------------------------------- + + assert_eq!( + help_markdown_command_custom( + &app, + &MarkdownOptions::new().show_footer(false) + ), + "\ +# Command-Line Help for my-program-display-name + +This document contains the help content for the `my-program-name` command-line program. + +**Command Overview:** + +* [`my-program-name`↴](#my-program-name) + +## `my-program-name` + +This program does things. + +**Usage:** `my-program-bin-name [OPTIONS]` + +###### **Options:** + +* `-f ` +* `-h`, `--help` — Print help +* `-V`, `--version` — Print version + + + +" + ); +}