From 54f96af969247f448a48aa86cff721d2a0855895 Mon Sep 17 00:00:00 2001
From: Neko Ayaka <neko@ayaka.moe>
Date: Mon, 25 Dec 2023 14:40:27 +0800
Subject: [PATCH] docs: added documentations and help message for setup
 completions when used as kubectl plugin (#793)

* docs: added documentations and help message for setup completions when used as kubectl plugin

Signed-off-by: Neko Ayaka <fanshi.zhang@daocloud.io>

* docs: tune phrases for PowerShell

Signed-off-by: Neko Ayaka <fanshi.zhang@daocloud.io>

---------

Signed-off-by: Neko Ayaka <fanshi.zhang@daocloud.io>
---
 cmd/completion.go                             |  87 ++++++---
 docs/en-us/cli/kubecm_completion.md           | 182 +++++++++++++++---
 docs/zh-cn/cli/kubecm_completion.md           | 181 ++++++++++++++---
 .../kubectl_complete-kc.sh                    |   4 +
 4 files changed, 364 insertions(+), 90 deletions(-)
 create mode 100644 hack/kubectl-plugin-completion/kubectl_complete-kc.sh

diff --git a/cmd/completion.go b/cmd/completion.go
index 8c5e728b..6d28ce27 100644
--- a/cmd/completion.go
+++ b/cmd/completion.go
@@ -36,45 +36,80 @@ func (cc *CompletionCommand) Init() {
 }
 
 func longDetail() string {
-	return `To load completions:
+	return `To load completions for kubecm cli:
 
-Bash:
-  ` + "```" + `
-  $ source <(kubecm completion bash)
+For Bash users:
+
+  # To load completions for the current session, execute once:
+  source <(kubecm completion bash)
+
+  # To load completions for each session, execute once (you will need to start a new
+  # shell for this setup to take effect.):
 
-  # To load completions for each session, execute once:
   # Linux:
-  $ kubecm completion bash > /etc/bash_completion.d/kubecm
+  kubecm completion bash > /etc/bash_completion.d/kubecm
+
   # macOS:
-  $ kubecm completion bash > /usr/local/etc/bash_completion.d/kubecm
-  ` + "```" + `
-Zsh:
-  ` + "```" + `
+  kubecm completion bash > /usr/local/etc/bash_completion.d/kubecm
+
+For Zsh users, execute:
+
   # If shell completion is not already enabled in your environment,
   # you will need to enable it.  You can execute the following once:
 
-  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+  echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+  # To load completions for each session, execute once (you will need to start a new
+  # shell for this setup to take effect.):
+  kubecm completion zsh > "${fpath[1]}/_kubecm"
 
-  # To load completions for each session, execute once:
-  $ kubecm completion zsh > "${fpath[1]}/_kubecm"
+For fish users, execute:
 
-  # You will need to start a new shell for this setup to take effect.
-  ` + "```" + `
-fish:
-  ` + "```" + `
-  $ kubecm completion fish | source
+  # Load completions for the current session, execute once:
+  kubecm completion fish | source
 
-  # To load completions for each session, execute once:
-  $ kubecm completion fish > ~/.config/fish/completions/kubecm.fish
-  ` + "```" + `
-PowerShell:
-  ` + "```" + `
-  PS> kubecm completion powershell | Out-String | Invoke-Expression
+  # Load completions for each session, execute once (you will need to start a new
+  # shell for this setup to take effect.):
+  kubecm completion fish > ~/.config/fish/completions/kubecm.fish
+
+For PowerShell users, execute:
+
+  # To load completions for the current session, execute once:
+  kubecm completion powershell | Out-String | Invoke-Expression
 
   # To load completions for every new session, run:
-  PS> kubecm completion powershell > kubecm.ps1
+  kubecm completion powershell > kubecm.ps1
   # and source this file from your PowerShell profile.
-  ` + "```" + `
+
+---
+
+To load completions for kubectl kc when used as kubectl plugin:
+
+1. Use the following command as one-liner to add the completion to the current shell session:
+
+  mkdir -p ~/.config/.kubectl-plugin-completions
+  cat <<EOF >~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+  #!/usr/bin/env sh
+
+  # Call the __complete command passing it all arguments
+  kubectl kc __complete "\$@"
+  EOF
+  chmod +x ~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+
+2. Append the directory to the $PATH environment variable.
+
+For Bash users, execute:
+
+  echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.bashrc
+
+For Zsh users, execute:
+
+  echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.zshrc
+
+For fish users, execute:
+
+  fish_add_path ~/.config/.kubectl-plugin-completions
+
 ---
 `
 }
diff --git a/docs/en-us/cli/kubecm_completion.md b/docs/en-us/cli/kubecm_completion.md
index b821a4cb..ff215dfb 100644
--- a/docs/en-us/cli/kubecm_completion.md
+++ b/docs/en-us/cli/kubecm_completion.md
@@ -1,52 +1,171 @@
-## kubecm completion
+## `kubecm` completion
 
 Generate completion script
 
 ### Synopsis
 
-To load completions:
+Please follow the guide below to configure auto-completion for both regular `kubecm` and `kubectl kc` (as `kubectl` plugin).
+
+#### Configuration for auto-completion of `kubecm`
 
 Bash:
-  ```
-  $ source <(kubecm completion bash)
-
-  # To load completions for each session, execute once:
-  # Linux:
-  $ kubecm completion bash > /etc/bash_completion.d/kubecm
-  # macOS:
-  $ kubecm completion bash > /usr/local/etc/bash_completion.d/kubecm
-  ```
+
+```shell
+# To load completions for the current session, execute once:
+$ source <(kubecm completion bash)
+
+# To load completions for each session, execute once:
+# Linux:
+$ kubecm completion bash > /etc/bash_completion.d/kubecm
+
+# macOS:
+$ kubecm completion bash > /usr/local/etc/bash_completion.d/kubecm
+
+# You will need to start a new shell for this setup to take effect.
+```
+
 Zsh:
-  ```
-  # If shell completion is not already enabled in your environment,
-  # you will need to enable it.  You can execute the following once:
 
-  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+```shell
+# If shell completion is not already enabled in your environment,
+# you will need to enable it.  You can execute the following once:
+
+$ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+# To load completions for each session, execute once:
+$ kubecm completion zsh > "${fpath[1]}/_kubecm"
 
-  # To load completions for each session, execute once:
-  $ kubecm completion zsh > "${fpath[1]}/_kubecm"
+# You will need to start a new shell for this setup to take effect.
+```
 
-  # You will need to start a new shell for this setup to take effect.
-  ```
 fish:
-  ```
-  $ kubecm completion fish | source
 
-  # To load completions for each session, execute once:
-  $ kubecm completion fish > ~/.config/fish/completions/kubecm.fish
-  ```
+```shell
+# To load completions for the current session, execute once:
+$ kubecm completion fish | source
+
+# To load completions for each session, execute once:
+$ kubecm completion fish > ~/.config/fish/completions/kubecm.fish
+
+# You will need to start a new shell for this setup to take effect.
+```
+
 PowerShell:
-  ```
-  PS> kubecm completion powershell | Out-String | Invoke-Expression
 
-  # To load completions for every new session, run:
-  PS> kubecm completion powershell > kubecm.ps1
-  # and source this file from your PowerShell profile.
-  ```
----
+```powershell
+# To load completions for the current session, execute once:
+PS> kubecm completion powershell | Out-String | Invoke-Expression
+
+# To load completions for every new session, run:
+PS> kubecm completion powershell > kubecm.ps1
+# and source this file from your PowerShell profile.
+```
+
+#### Configuration for auto-completion of `kubectl kc` (as `kubectl` plugin)
+
+Unlike direct execution of `kubecm`, when executed as a `kubectl` plugin (i.e., using `kubecm` installed with [`krew`](https://krew.sigs.k8s.io/) or invoked as `kubectl kc`), auto-completion requires some additional configuration based on [Configuration for auto-completion of `kubecm`](#configuration-for-auto-completion-of-kubecm) to enable auto-completion when use `kubectl kc` + <kbd>TAB</kbd>.
+
+> How does this work?
+>
+> In a nut shell, `kubectl` looks for a executable script or binary that named with the `kubectl_complete-<plugin-name>` pattern as a **convention** in the `$PATH` environment variable. If it does find, `kubectl` will pass the arguments that calls from `kubectl <plugin-name>` to the conventionally configured auto-completion script to seek out for completion candidates list.
+
+Therefore, in order for the auto-completion of `kubectl kc` + <kbd>TAB</kbd> to work, there are several options for you to choose from and configure.
+
+Note: **PowerShell's auto-completion requires no additional configuration and works right out of the box.**
+
+##### Use pre-written auto-completion script
+
+You can download the pre-written auto-completion script and configure it automatically by executing the following command:
+
+```shell
+mkdir -p ~/.config/.kubectl-plugin-completions && \
+  curl -LO "https://raw.githubusercontent.com/sunny0826/kubecm/master/hack/kubectl-plugin-completions/kubectl_complete-kc.sh" && \
+  mv kubectl_complete-kc.sh ~/.config/.kubectl-plugin-completions/kubectl_complete-kc && \
+  chmod +x ~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+```
+
+Append the `~/.config/.kubectl-plugin-completions` directory we've created just now to the `$PATH` environment variable to satisfy the auto-completion convention of the `kubectl` plugin:
+
+Bash:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.bashrc
+```
+
+Zsh:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.zshrc
+```
 
+Fish:
 
+```shell
+fish_add_path ~/.config/.kubectl-plugin-completions
 ```
+
+##### Manually configure auto-completion script
+
+1. Create the directory `.config/.kubectl-plugin-completions` for the auto-completion scripts:
+
+```shell
+mkdir -p ~/.config/.kubectl-plugin-completions
+```
+
+2. Write the following content into an executable shell script named `kubectl_complete-kc` in this directory:
+
+```shell
+#!/usr/bin/env sh
+
+# Call the __complete command passing it all arguments
+kubectl kc __complete "$@"
+```
+
+You can also complete this step as one-liner using the following command:
+
+```shell
+cat <<EOF >~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+#!/usr/bin/env sh
+
+# Call the __complete command passing it all arguments
+kubectl kc __complete "\$@"
+EOF
+```
+
+3. Add executable permissions to the file:
+
+```shell
+chmod +x ~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+```
+
+Append the `~/.config/.kubectl-plugin-completion` directory we've created just now to the `$PATH` environment variable to satisfy the auto-completion convention of the `kubectl` plugin:
+
+Bash:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.bashrc
+```
+
+Zsh:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.zshrc
+```
+
+Fish:
+
+```shell
+fish_add_path ~/.config/.kubectl-plugin-completions
+```
+
+##### Use a `kubectl` plugin `kubectl-plugin_completion` to automatically generate and configure
+
+Please refer to the [`kubectl-plugin_completion`](https://github.com/marckhouzam/kubectl-plugin_completion) plugin's documentation for configuration.
+
+---
+
+
+```shell
 kubecm completion [bash|zsh|fish|powershell] [flags]
 ```
 
@@ -68,4 +187,3 @@ kubecm completion [bash|zsh|fish|powershell] [flags]
 ### SEE ALSO
 
 * [kubecm](kubecm.md)	 - KubeConfig Manager.
-
diff --git a/docs/zh-cn/cli/kubecm_completion.md b/docs/zh-cn/cli/kubecm_completion.md
index 5582f1ce..6ba8ee26 100644
--- a/docs/zh-cn/cli/kubecm_completion.md
+++ b/docs/zh-cn/cli/kubecm_completion.md
@@ -1,52 +1,169 @@
-## kubecm completion
+## `kubecm` completion
 
-生成 bash/zsh 自动补全脚本
+生成自动补全脚本
 
 ### 简介
 
-To load completions:
+请根据下面的指南进行操作为普通的 `kubecm` 和 `kubectl kc`（`kubectl` 插件）配置基本的自动补全功能。
+
+#### 配置 `kubecm` 的自动补全
 
 Bash:
-  ```
-  $ source <(kubecm completion bash)
-
-  # To load completions for each session, execute once:
-  # Linux:
-  $ kubecm completion bash > /etc/bash_completion.d/kubecm
-  # macOS:
-  $ kubecm completion bash > /usr/local/etc/bash_completion.d/kubecm
-  ```
+
+```shell
+$ source <(kubecm completion bash)
+
+# 可以通过运行一次下面的命令来为将来的每一个 Shell 会话激活自动补全：
+# Linux:
+$ kubecm completion bash > /etc/bash_completion.d/kubecm
+
+# macOS:
+$ kubecm completion bash > /usr/local/etc/bash_completion.d/kubecm
+
+# 在执行完毕后，你需要重新打开一个新的终端才能使补全脚本生效。
+```
+
 Zsh:
-  ```
-  # If shell completion is not already enabled in your environment,
-  # you will need to enable it.  You can execute the following once:
 
-  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+```shell
+# 如果你当前的 zsh 环境中尚未激活自动补全的功能，你需要先激活它。你
+# 可以通过下面的命令来激活：
 
-  # To load completions for each session, execute once:
-  $ kubecm completion zsh > "${fpath[1]}/_kubecm"
+$ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+# 可以通过运行一次下面的命令来为将来的每一个 Shell 会话激活自动补全：
+$ kubecm completion zsh > "${fpath[1]}/_kubecm"
+
+# 在执行完毕后，你需要重新打开一个新的终端才能使补全脚本生效。
+```
 
-  # You will need to start a new shell for this setup to take effect.
-  ```
 fish:
-  ```
-  $ kubecm completion fish | source
 
-  # To load completions for each session, execute once:
-  $ kubecm completion fish > ~/.config/fish/completions/kubecm.fish
-  ```
+```shell
+# 可以通过运行一次下面的命令来为当前的 Shell 会话激活自动补全：
+$ kubecm completion fish | source
+
+# 可以通过运行一次下面的命令来为将来的每一个 Shell 会话激活自动补全：
+$ kubecm completion fish > ~/.config/fish/completions/kubecm.fish
+
+# 在执行完毕后，你需要重新打开一个新的终端才能使补全脚本生效。
+```
+
 PowerShell:
-  ```
-  PS> kubecm completion powershell | Out-String | Invoke-Expression
 
-  # To load completions for every new session, run:
-  PS> kubecm completion powershell > kubecm.ps1
-  # and source this file from your PowerShell profile.
-  ```
----
+```shell
+# 可以通过运行一次下面的命令来为当前的 Shell 会话激活自动补全：
+PS> kubecm completion powershell | Out-String | Invoke-Expression
+
+# 为将来的每一个 Shell 会话激活自动补全，请执行下面的命令：
+PS> kubecm completion powershell > kubecm.ps1
+# 然后在 PowerShell 的 profile 中引入这个文件。
+```
 
+#### 为作为 `kubectl` 插件的 `kubecm` 配置自动补全
 
+与直接执行 `kubecm` 不同的是，在作为 `kubectl` 插件（即使用 [`krew`](https://krew.sigs.k8s.io/) 安装的 `kubecm`，或者以 `kubectl kc` 的形式调用）执行时，自动补全需要在[配置 `kubecm` 的自动补全](#配置-kubecm-的自动补全)的基础上进行一些额外的配置才能使 `kubectl kc` + <kbd>TAB</kbd> 时的自动补全生效。
+
+> 原理是什么？
+>
+> 简而言之，`kubectl` 的插件会在 `$PATH` 环境变量中寻找遵循 `kubectl_complete-<插件名>` 命名规则的可执行文件作为**约定**，然后在调用 `kubectl <插件名>` 的时候由 `kubectl` 展开参数并传递参数给调用这个按约定配置的自动补全脚本。
+
+因此，为了使 `kubectl kc` + <kbd>TAB</kbd> 的自动补全生效，下面有几种方案。
+
+Note: **PowerShell 的自动补全无需额外配置，开箱即用。**
+
+##### 使用预编写的自动补全脚本
+
+你可以通过执行下面的命令来下载预编写的自动补全脚本并完成配置：
+
+```shell
+mkdir -p ~/.config/.kubectl-plugin-completions && \
+  curl -LO "https://raw.githubusercontent.com/sunny0826/kubecm/master/hack/kubectl-plugin-completions/kubectl_complete-kc.sh" && \
+  mv kubectl_complete-kc.sh ~/.config/.kubectl-plugin-completions/kubectl_complete-kc && \
+  chmod +x ~/.config/.kubectl-plugin-completions/kubectl_complete-kc
 ```
+
+将 `~/.config/.kubectl-plugin-completions` 目录追加到 `$PATH` 环境变量中，以满足 `kubectl` 插件的自动补全约定：
+
+Bash:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.bashrc
+```
+
+Zsh:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.zshrc
+```
+
+Fish:
+
+```shell
+fish_add_path ~/.config/.kubectl-plugin-completions
+```
+
+##### 手动创建
+
+1. 创建用于放置自动补全脚本的目录 `.config/.kubectl-plugin-completions`：
+
+```shell
+mkdir -p ~/.config/.kubectl-plugin-completions
+```
+
+2. 填充下面的内容到该目录下一个名为 `kubectl_complete-kc` 的可执行文件中：
+
+```shell
+#!/usr/bin/env sh
+
+# Call the __complete command passing it all arguments
+kubectl kc __complete "$@"
+```
+
+你也可以通过下面的命令来一次性完成这一步骤：
+
+```shell
+cat <<EOF >~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+#!/usr/bin/env sh
+
+# Call the __complete command passing it all arguments
+kubectl kc __complete "\$@"
+EOF
+```
+
+3. 为该文件添加可执行权限：
+
+```shell
+chmod +x ~/.config/.kubectl-plugin-completions/kubectl_complete-kc
+```
+
+4. 将该目录追加到 `$PATH` 环境变量中，以满足 `kubectl` 插件的自动补全约定：
+
+Bash:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.bashrc
+```
+
+Zsh:
+
+```shell
+echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.zshrc
+```
+
+Fish:
+
+```shell
+fish_add_path ~/.config/.kubectl-plugin-completions
+```
+
+##### 使用 `kubectl-plugin_completion` 插件自动生成和配置
+
+请参考 [`kubectl-plugin_completion`](https://github.com/marckhouzam/kubectl-plugin_completion) 插件的文档进行配置。
+
+---
+
+```shell
 kubecm completion [bash|zsh|fish|powershell] [flags]
 ```
 
diff --git a/hack/kubectl-plugin-completion/kubectl_complete-kc.sh b/hack/kubectl-plugin-completion/kubectl_complete-kc.sh
new file mode 100644
index 00000000..bc9c2ee3
--- /dev/null
+++ b/hack/kubectl-plugin-completion/kubectl_complete-kc.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+
+# Call the __complete command passing it all arguments
+kubectl kc __complete "$@"