Consolidating clap flags into `basic`, `advanced`, `hidden`

[macladson]

Issue

Currently we have a lot of CLI flags and arguments, many of which are totally irrelevant to 99% of users however the flags are useful to have. We have generally built Lighthouse with the idea that a dynamic value adjusted by flag is always better than a hard-coded constant. I 100% agree with this, however it has led to a large amount of flag bloat, which in my opinion makes --help unwieldy to users. It becomes confusing and difficult to find flags which are relevant, especially as a new user.

Potential Solutions

1. Be more aggressive with .hidden(true). This has the downside of being unable to ever show the hidden flags in the help text, which even means the Lighthouse book won't have the other flags. A better solution in my opinion is:

2. Override the help headings, then write custom help functions which dynamically hide certain headings. For example it might look like:

➜ lighthouse bn --help-advanced
Usage: lighthouse [OPTIONS] --basic-field <FIELD>

Options:
  -h, --help     Print help
  -H --help-advanced      Print advanced help
  -V, --version      Print version

Basic Flags:
  -f, --basic-field <FIELD>  A basic field
  -s, --basic-setting <SETTING>    Some basic setting

Advanced Flags:
      --advanced-setting <SETTING>  Some advanced setting

Then, running --help would remove the Advanced flags from the output.

We could even add a --help-hidden flag which shows all the hidden flags (this might not be desired if we have certain experimental flags we want users to avoid, but they could technically just look at the source code. (We could even hide the --help-hidden command)

What is the appetite for solution #2. Do people feel that flag bloat is a real issue?

[dapplion]

I would vote to be more aggressive with hidden flags. And then maybe display all of them in the book?

[michaelsproul]

I think rather than fully hiding flags I like the idea of having advanced flags that only show under --help-advanced. And a hidden --help-hidden is a cute idea too.

[AgeManning]

I support this too 👍

I do think some flags are very specific to devs and can be hidden, because the devs can just lookup the code (I still do this for misc flags that I wrote myself, but forgot how to use), so support this, in combination with more aggressive hiding.