Document different options for activating completions

[epage]

Maintainer's notes

We should document each solution (flag, subcommand, env var) and the trade offs. We should probably make env variable the default.

---

Discussed in https://github.com/clap-rs/clap/discussions/3926

^{Originally posted by AndreasBackx July 13, 2022} We have a nice macro that automatically adds autocomplete to your Clap CLI. We are currently doing this via a subcommand generate-completions. Though we realise that this approach makes it impossible to automatically generate completions for certain CLIs:

#[derive(Parser, Debug)]
pub struct Args {
    foo: String,
}

Imagine we have that very simple CLI and we want to add a subcommand. foo is a required argument so if we want to automate the autocomplete generation by adding eval $(cli generate-completions) or by exporting it to /usr/share/bash-completion/completions/cli for Bash, the CLI will complain that foo wasn't passed.

Therefore it seems right now that we should avoid depending on Clap parsing as part of autocomplete generation. Perhaps the people at Click realised this earlier as that is what they are doing: https://click.palletsprojects.com/en/8.1.x/shell-completion/.

So I have a few questions that spring from this:

1. Is my understanding correct? Would love to hear there might be a mistake.
2. What do you think of the solution, can you perhaps think of another solution?
3. Should the documentations surrounding this perhaps be updated?
4. With this in mind, perhaps we could integrate clap_complete into clap as a feature? If enabled, you can get autocomplete automatically in your CLI in a similar way to Click.

Funnily enough we didn't initially face this problem because of how command_for_update sets required to false, see #3924.