From 6d560160714df23b73b15b3f9dcf08950d6997ac Mon Sep 17 00:00:00 2001 From: shannmu <shanmu1901@gmail.com> Date: Wed, 10 Jul 2024 00:22:23 +0800 Subject: [PATCH] docs: Add document comments how to source dynamic completions --- clap_complete/src/dynamic/shells/mod.rs | 72 +++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/clap_complete/src/dynamic/shells/mod.rs b/clap_complete/src/dynamic/shells/mod.rs index 6cfed97ed5e..9eb6106da86 100644 --- a/clap_complete/src/dynamic/shells/mod.rs +++ b/clap_complete/src/dynamic/shells/mod.rs @@ -16,6 +16,78 @@ use crate::dynamic::Completer as _; /// A subcommand definition to `flatten` into your CLI /// /// This provides a one-stop solution for integrating completions into your CLI +/// +/// # Examples +/// +/// The following example shows how to integrate completions into your CLI and generate completions. +/// +/// 1. Build an application with derive API. +/// 2. Call `clap_complete::dynamic::shells::CompleteCommand::augment_subcommands` to add the `complete` subcommand into the application. +/// 3. Call `get_matches()`, or any of the other normal methods directly after. +/// +/// For example: +/// +/// ```no_run +/// // src/main.rs +/// use clap::{CommandFactory, FromArgMatches, Parser, Subcommand}; +/// use clap_complete::dynamic::shells::CompleteCommand; +/// +/// #[derive(Parser, Debug)] +/// #[clap(name = "dynamic", about = "A dynamic command line tool")] +/// struct Cli { +/// /// The subcommand to run complete +/// #[command(subcommand)] +/// complete: Option<CompleteCommand>, +/// /// Input file path +/// #[clap(short, long, value_hint = clap::ValueHint::FilePath)] +/// input: Option<String>, +/// /// Output format +/// #[clap(short = 'F', long, value_parser = ["json", "yaml", "toml"])] +/// format: Option<String>, +/// } +/// +/// fn main() { +/// let cli = Cli::parse(); +/// if let Some(completions) = cli.complete { +/// completions.complete(&mut Cli::command()); +/// } +/// +/// // normal logic continues... +/// } +///``` +/// +/// # Usage for complete subcommand: +/// +/// To generate shell completion scripts and source them, we can use the following command. +/// +/// **NOTE**: If you have set a custom shell configuration file, +/// please remember to modify the redirection output file in the following command. +/// +/// - Bash +/// ```bash +/// echo "source <(your_program complete --shell bash --register -)" >> ~/.bashrc +/// ``` +/// +/// - Fish +/// ```fish +/// echo "source (your_program complete --shell fish --register - | psub)" >> ~/.config/fish/config.fish +/// ``` +/// +/// - Zsh +/// ```zsh +/// echo "source <(your_program complete --shell zsh --register -)" >> ~/.zshrc +/// ``` +/// +/// - Elvish +/// ```elvish +/// echo "eval (your_program complete --shell elvish --register -)" >> ~/.elvish/rc.elv +/// ``` +/// +/// - Powershell +/// ```powershell +/// echo "your_program complete --shell powershell --register - | Invoke-Expression" >> $PROFILE +/// ``` +/// #[derive(clap::Subcommand)] #[allow(missing_docs)] #[derive(Clone, Debug)]