Merge pull request #5586 from shannmu/glue_documentation

docs: Add document comments how to source dynamic completions

clap_complete/src/dynamic/shells/mod.rs

@@ -20,6 +20,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)]