docs: enhance shell completion documentation with practical examples (#2305)

Improve the documentation for shell completion by:

- Adding detailed step-by-step setup instructions for each supported shell (Bash, Zsh, Fish, PowerShell)

- Including both temporary and permanent setup options

- Providing clear examples with copy-paste ready commands

- Adding a section on testing completion functionality

- Organizing content with clear section headings

- Standardizing reference links to related documentation

This enhancement makes it easier for users to set up and use shell completion with Chainsaw, improving the overall user experience.

Signed-off-by: Karthik babu Manam <[email protected]>
Co-authored-by: Charles-Edouard Brétéché <[email protected]>

Author: karthikmanam

website/docs/quick-start/completion.md

@@ -1,10 +1,113 @@
-# Shell completion
+# Shell Completion
 
-Once installed, use `chainsaw completion` command to generate and register the autocompletion script for the specified shell.
+Chainsaw provides shell completion support for Bash, Zsh, Fish, and PowerShell. Once set up, you can use the <Tab> key to auto-complete chainsaw commands, flags, and even some arguments, which significantly improves the command-line experience.
 
-Supported shells are:
+## Generating Completion Scripts
 
-- [bash](../reference/commands/chainsaw_completion_bash.md)
-- [fish](../reference/commands/chainsaw_completion_fish.md)
-- [powershell](../reference/commands/chainsaw_completion_powershell.md)
-- [zsh](../reference/commands/chainsaw_completion_zsh.md)
+You can generate shell completion scripts using the `chainsaw completion` command:
+
+```bash
+# For Bash
+chainsaw completion bash
+
+# For Zsh
+chainsaw completion zsh
+
+# For Fish
+chainsaw completion fish
+
+# For PowerShell
+chainsaw completion powershell
+```
+
+## Setting Up Completion
+
+### Bash
+
+To enable completion in your current Bash session:
+
+```bash
+source <(chainsaw completion bash)
+```
+
+To enable completion for all sessions, add the above line to your `~/.bashrc` file:
+
+```bash
+echo 'source <(chainsaw completion bash)' >> ~/.bashrc
+```
+
+Alternatively, you can save the completion script to the bash-completion directory:
+
+```bash
+# On Linux
+chainsaw completion bash > /etc/bash_completion.d/chainsaw
+
+# On macOS with Homebrew
+chainsaw completion bash > $(brew --prefix)/etc/bash_completion.d/chainsaw
+```
+
+### Zsh
+
+To enable completion in your current Zsh session:
+
+```bash
+source <(chainsaw completion zsh)
+```
+
+To enable completion for all sessions, add the above line to your `~/.zshrc` file:
+
+```bash
+echo 'source <(chainsaw completion zsh)' >> ~/.zshrc
+```
+
+Alternatively, you can save the completion script to a directory in your `$fpath`:
+
+```bash
+# Create a directory for completions if it doesn't exist
+mkdir -p ~/.zsh/completion
+# Generate and save the completion script
+chainsaw completion zsh > ~/.zsh/completion/_chainsaw
+
+# Make sure the directory is in your fpath by adding to ~/.zshrc:
+echo 'fpath=(~/.zsh/completion $fpath)' >> ~/.zshrc
+echo 'autoload -U compinit; compinit' >> ~/.zshrc
+```
+
+### Fish
+
+To enable completion in Fish:
+
+```bash
+chainsaw completion fish > ~/.config/fish/completions/chainsaw.fish
+```
+
+### PowerShell
+
+To enable completion in PowerShell:
+
+```powershell
+chainsaw completion powershell | Out-String | Invoke-Expression
+```
+
+To make it persistent, add the above line to your PowerShell profile:
+
+```powershell
+# Find the profile path
+echo $PROFILE
+
+# Add the completion command to your profile
+chainsaw completion powershell | Out-String | Out-File -Append $PROFILE
+```
+
+## Testing Completion
+
+After setting up completion, you can test it by typing `chainsaw` followed by a space and pressing <Tab>. This should show available subcommands. You can also try typing partial commands like `chainsaw te` and then pressing <Tab>, which should complete to `chainsaw test`.
+
+## Detailed Reference
+
+For more detailed information about each completion command, see the reference documentation:
+
+- [Bash Completion](../reference/commands/chainsaw_completion_bash.md)
+- [Fish Completion](../reference/commands/chainsaw_completion_fish.md)
+- [PowerShell Completion](../reference/commands/chainsaw_completion_powershell.md)
+- [Zsh Completion](../reference/commands/chainsaw_completion_zsh.md)