feat(help): Opt-in to flatten subcommands into parent command help #5206

epage · 2023-11-09T21:24:15Z

When using globals, people tend to make all of the top-level arguments global and cascading them through would just bloat the output.

SUPERCILEX · 2023-11-10T20:24:44Z

I think the main bummer with this approach is that it can't be dynamic, right? As in you'd need to decide without user input (or maybe use environment variables, but that's unpleasant) whether or not to flatten the help.

Then again, is the flattening option propagation NOT recursive? As in it only applies to the current command? That seems pretty reasonable to me as you kind of want to get a holistic picture of the CLI from the top-level. My concern is that it'll be overwhelming for large CLIs (think as big as git), but as long as propagation isn't recursive, the developer could decide to put flattening a few levels down the hierarchy to keep the top-level from being a dozen pages long.

My beef with the non-dynamism is that I really like the idea of being able to do a grep on an entire subsection of the CLI as a user. E.g. cli help --recursive | grep thing_im_trying_to_see_if_exists. If the developer picks when flattening happens, I can't grep all of help predictably.

epage · 2023-11-10T21:00:12Z

The focus / intent of this is to provide an experience similar to git stash. Some subcommands are commands in their own right (git diff) while some are really modes of the parent (git stash pop).

My beef with the non-dynamism is that I really like the idea of being able to do a grep on an entire subsection of the CLI as a user. E.g. cli help --recursive | grep thing_im_trying_to_see_if_exists. If the developer picks when flattening happens, I can't grep all of help predictably.

btw I'm not finding this use case raised in #4813. Instead it only talks about golden state testing (which can be solved other ways) and "acting like a man page" which I've not seen any "man page"s that look anything like the recursive idea except for ones like git stash which is the case we are covering.

SUPERCILEX · 2023-11-10T21:32:02Z

The focus / intent of this is to provide an experience similar to git stash. Some subcommands are commands in their own right (git diff) while some are really modes of the parent (git stash pop).

Got it, in that case I don't think a --recursive flag is incompatible with the stash use case. Though it still seems to me like --recursive is a superset of the functionality as long as you can default it to true (in which case I believe it's equivalent to this PR's flatten_help option).

Yeah, my bad for not being clearer on "acting like a man page." The searchability/everything being in the same place is what I mean by that. You get the entire CLI's API in a single place which means you can do things like search it, use it for golden testing, make it work similar to git stash, etc. I should have made the generalization clearer.

Here's how the ocaml CLI does it:
https://github.com/SUPERCILEX/hardcaml_riscv/blob/15eadec09fb22f83f3d01992e90d297ff84ccd7d/hard/arty/dune#L20
Output: https://github.com/SUPERCILEX/hardcaml_riscv/blob/15eadec09fb22f83f3d01992e90d297ff84ccd7d/hard/arty/command-reference.golden
BTW this reminds me, what was the reasoning for not adding a -? alias for -h? Would be here.

As for golden testing, I probably wouldn't use flatten_help as I already have the "paste every subcommand help" expansion code in my library:
https://github.com/SUPERCILEX/supercilex-tests/blob/b93f16c274f27efb27b38e7df31eac955d3a187a/src/lib.rs#L90-L134

epage · 2023-11-10T22:21:48Z

Though it still seems to me like --recursive is a superset of the functionality as long as you can default it to true (in which case I believe it's equivalent to this PR's flatten_help option).

If the formatting of flatten_help is sufficient, I think everything is in place for a CLI to provide this on its own.

BTW this reminds me, what was the reasoning for not adding a -? alias for -h?

Unsure if its come up before.

SUPERCILEX · 2023-11-10T23:06:43Z

If the formatting of flatten_help is sufficient, I think everything is in place for a CLI to provide this on its own.

I'm confused, how would this work? Is that idea that the CLI would call flatten_help formatting routines manually?

epage · 2023-11-11T01:52:28Z

Create your own help subcommand. When run, take your command and recursively set flatten_help on everything and then print the help.

Apanatshka · 2023-11-23T14:05:58Z

I'm really happy that you landed this feature! It works well enough for my purposes, thanks for working on it. However, I did notice a few edge cases that aren't very clean:

The help of the subcommands include the crate description pulled in by #[command(about)] on the top-level struct, which looks very redundant.
Subcommands annotated with #[clap(hide(true))] are not hidden in the subcommands overview.

If you like I can file separate issues for these problems?

epage · 2023-11-23T14:43:28Z

Issues would be appreciated

Apanatshka · 2023-11-27T13:32:06Z

Ok. I've opened #5225 and #5226, just mentioning it here so they are cross-linked.

I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`](https://github.com/matklad/cargo-xtask ) so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in clap-rs/clap#5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. #### Cargo Alias My first attempt was to set up a cargo [alias](https://doc.rust-lang.org/cargo/reference/config.html#alias) to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ```

I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in clap-rs/clap#5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias

I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file rust-lang/cargo#13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in clap-rs/clap#5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias

epage added 2 commits November 9, 2023 13:31

feat(help): Allow controlling flattening

a1fd922

feat(help): Allow flattening usage

caf5cdc

epage mentioned this pull request Nov 9, 2023

Display help for all subcommands at the same time #1334

Closed

epage added 5 commits November 9, 2023 15:32

feat(help): Allow flattening help

66d2bcb

fix(help): Be consistent in long/short help

9e5f93d

fix(help): Gloss over globals with flatten

c9a7ef0

When using globals, people tend to make all of the top-level arguments global and cascading them through would just bloat the output.

refactor(help): Pull out flat subcommands

4bef91c

fix(help): Recurse help flattening

9c0f7a7

epage force-pushed the flatten branch 2 times, most recently from 3403f44 to aeb93d4 Compare November 9, 2023 21:46

epage mentioned this pull request Nov 9, 2023

Add -r, --recursive flags to help command #4813

Open

2 tasks

epage force-pushed the flatten branch from aeb93d4 to 9c0f7a7 Compare November 9, 2023 22:56

epage merged commit 6b2a2cc into clap-rs:master Nov 10, 2023
22 checks passed

epage deleted the flatten branch November 10, 2023 22:21

epage mentioned this pull request Nov 11, 2023

Support command chaining #2222

Open

epage mentioned this pull request Feb 2, 2024

Respect flatten_help in man pages #5337

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(help): Opt-in to flatten subcommands into parent command help #5206

feat(help): Opt-in to flatten subcommands into parent command help #5206

epage commented Nov 9, 2023

SUPERCILEX commented Nov 10, 2023

epage commented Nov 10, 2023

SUPERCILEX commented Nov 10, 2023

epage commented Nov 10, 2023

SUPERCILEX commented Nov 10, 2023

epage commented Nov 11, 2023

Apanatshka commented Nov 23, 2023

epage commented Nov 23, 2023

Apanatshka commented Nov 27, 2023

feat(help): Opt-in to flatten subcommands into parent command help #5206

feat(help): Opt-in to flatten subcommands into parent command help #5206

Conversation

epage commented Nov 9, 2023

SUPERCILEX commented Nov 10, 2023

epage commented Nov 10, 2023

SUPERCILEX commented Nov 10, 2023

epage commented Nov 10, 2023

SUPERCILEX commented Nov 10, 2023

epage commented Nov 11, 2023

Apanatshka commented Nov 23, 2023

epage commented Nov 23, 2023

Apanatshka commented Nov 27, 2023