Add Subcommand help headings #5819
Conversation
| /// [`Command::subcommand_help_heading`]: crate::Command::subcommand_help_heading() | ||
| #[inline] | ||
| #[must_use] | ||
| pub fn next_subcommand_help_heading(mut self, heading: impl IntoResettable<Str>) -> Self { |
There was a problem hiding this comment.
This will also need a way to set the help heading for the current command
There was a problem hiding this comment.
This will likely run into name conflicts with subcommand_help_heading. We should probably deprecate that and migrate people over to setting next_subcommand_help_heading.
| /// [`Command::subcommand_help_heading`]: crate::Command::subcommand_help_heading() | ||
| #[inline] | ||
| #[must_use] | ||
| pub fn next_subcommand_help_heading(mut self, heading: impl IntoResettable<Str>) -> Self { |
There was a problem hiding this comment.
The derive has special handling for regular help headings, so we should probably have the same for these
| /// [`Command::subcommand_help_heading`]: crate::Command::subcommand_help_heading() | ||
| #[inline] | ||
| #[must_use] | ||
| pub fn next_subcommand_help_heading(mut self, heading: impl IntoResettable<Str>) -> Self { |
There was a problem hiding this comment.
Should we only have one next_help_heading?
There was a problem hiding this comment.
Good question, that would make api simpler, but I'd rather have clear separation between subcommand and parameter heading
| Commands: | ||
| help Print this message or the help of the given subcommand(s) |
There was a problem hiding this comment.
Before this can move forward, we need to come to a resolution on help. The initial discussion should be on #1553. If we need to make new issues off of that, then we can migrate from there.
|
Hey, I needed this feature for a tool I am writing, that has a lot of complex commands. So I rebased the PR in Kamuno@400dd85 Thank you all for the hard work you are doing. :) Great library and really useful PR! |
|
Please merge this, it fixes a painful problem. Without it, I would need a serious code enshittification to change my code from declarative derive subcommands (all 27 of them) to an ugly mix with builder patterns that will not work well anyway, just to show these section headings. |
This can't be merged as is. Someone will need to step up and finish this work
Why would the lack of this require mixing derive with builder? |
Because I cannot make section headings on subcommands enum in current clap version. The disparate bits and pieces of clap suggestions are saying something like "You can have subcommand section headings if you use builder, but not derive, so if you have a bunch of derived structures, you will have to glue them with builder to have the section headings". It loses abiiltiy to make back Opts structure from parsed args though, so will require a lot of noisy refactoring anyway. With the changes in this PR I can make section headings, the only two thing that are not possible is to 1) order them properly like I need to, 2) rename section headings back to "Commands" in the subcommand helps (it looks weird). |
|
Related discussion and changes. |
What is the process for taking over the PR to finish up the work and get it ready to merge? I am interested in seeing this to merging if possible. |
|
Note that there is still design discussion that needs to happen before moving forward on this PR, see #5819 (comment) (the issue is marked "waiting on design", not one of our "ready to implement labels). After that, I've not checked to see how bad the conflicts are to see if this just needs a |
6 participants
Group subcommands displayed in help (#1553)
This is for help only, does not affect matching.
I've done the builder part, still figuring out derive support
(ah - it works automatically by setting subcommand_help_header=Some("foo"). I'd probably should just document it somewhere).
This is done the same way grouping args works: subcommand has optional subcommand_help_heading.
If provided, it will be used to group commands visually when displaying subcommand help.
so that we can go from
Commands:
cmd1 ...
cmd2 ...
help ...
to
Commands:
help ...
Utility commands:
cmd1 ...
cmd2 ....
Nothing changes if groups aren't used. See tests for examples.
Issues:
having subcommand_heading and subcommand_help_heading may be confusing, maybe naming should change.