Support grouped options in markdown output #48
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: leighmcculloch <[email protected]>
Co-authored-by: leighmcculloch <[email protected]>
Co-authored-by: leighmcculloch <[email protected]>
Co-authored-by: leighmcculloch <[email protected]>
Implement support for clap argument help headings in markdown generation
leighmcculloch
commented
Aug 14, 2025
Comment on lines
+143
to
+175
| #[test] | ||
| fn test_empty_help_heading() { | ||
| // Test edge case where help_heading is an empty string | ||
| let app = Command::new("empty-heading-app") | ||
| .about("Test app with empty help heading") | ||
| .arg( | ||
| Arg::new("verbose") | ||
| .short('v') | ||
| .long("verbose") | ||
| .help("Enable verbose output") | ||
| .help_heading("") // Empty string | ||
| .action(clap::ArgAction::SetTrue), | ||
| ) | ||
| .arg( | ||
| Arg::new("debug") | ||
| .short('d') | ||
| .long("debug") | ||
| .help("Enable debug output") | ||
| .help_heading("Debug Options") | ||
| .action(clap::ArgAction::SetTrue), | ||
| ); | ||
|
|
||
| let output = help_markdown_command_custom( | ||
| &app, | ||
| &MarkdownOptions::new().show_footer(false), | ||
| ); | ||
|
|
||
| // Should have both empty heading section and Debug Options section | ||
| assert!(output.contains("###### **:**")); // Empty heading | ||
| assert!(output.contains("###### **Debug Options:**")); | ||
| assert!(output.contains("Enable verbose output")); | ||
| assert!(output.contains("Enable debug output")); | ||
| } |
Author
There was a problem hiding this comment.
This behaviour with the empty case probably seems a bit odd, but it is consistent with how clap renders an empty help heading.
killercup
approved these changes
Sep 25, 2025
killercup
left a comment
killercup
left a comment
There was a problem hiding this comment.
Needed this feature and was happy to see this PR! Works great :)
leighmcculloch
added a commit
to stellar/stellar-cli
that referenced
this pull request
Nov 3, 2025
### What Move the doc-gen binary code into its own crate, separate from the soroban-cli crate, and have it be dependent on the unmerged pull request to clap-markdown that adds support for grouping cli options: - ConnorGray/clap-markdown#48 ### Why The grouped options experience is a massive improvement. It makes the help documentation easier to scan and understand. It's the way the options are organised on the command line and the help markdown documentation should follow suite. While the pull request adds the feature upstream, the pull request hasn't been accepted yet. The clap-markdown dependency isn't needed for the stellar-cli other than doc-gen, so it is in any case good to get the dependency outside of the soroban-cli crate, so that it isn't downloaded by cargo everytime someone installs the stellar-cli. Moving doc-gen into its own crate is trivial because the soroban-cli is designed to be embedded, and achieves that. Additionally because the doc-gen crate does not need to be published it can reference the unreleased pull request without issue.
killercup
added a commit
to Softleif/clap-markdown
that referenced
this pull request
Dec 17, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
Add support for grouping options under the help headings in markdown output.
Why
Clap supports custom help headings for options. Options assigned a help heading will appear in the terminal output to be grouped under that help heading. For example:
Today clap-markdown renders all options under a single heading,
Options.With this change clap-markdown groups options under their help headings, reflecting the same experience that clap provides on the command line.
For commands with a large number of options that make use of help headings, this significantly lowers the cognitive load of reading the help when rendered in markdown.
cc @fnando