update installation documentation

docs/command_completion.md

@@ -1,7 +1,6 @@
 # Command completion 
 
-Currently, command line completion is not pre-installed in any installation method.
-You need to do it manually.
+**Note**: this is only needed for `homebrew` and `MacPorts` installations, as when installing the shell function mannually via [source the shell function](#source-the-shell-function), the completion script is already included.
 
 Install the completion script by running:
 

docs/installation.md

@@ -1,108 +1,98 @@
 # Installation
 
-## `switch` command
+The kubeswitch installation consists of both a `switcher` binary and a shell script which needs to be sourced.
 
-### Option 1a - Homebrew
+**NOTE**: to invoke kubeswitch, do not call the `switcher` binary directly from the command line. 
+Instead, use the sourced shell function as described in [source the shell function](#source-the-shell-function).
 
-Mac and Linux users can install both the `switch.sh` script and the `switcher` binary with `homebrew`.
-```
-$ brew install danielfoehrkn/switch/switch
-```
+## Option 1 - Homebrew
+**NOTE**: `fish` users please follow [install via Github releases](#option-2---github-releases) as the shell script only works for `zsh` and `bash` shells.
 
-Source the `switch()` wrapper and autocompletion by adding this into `.bashrc`/`.zshrc`:
+Install the `switcher` binary with `homebrew`.
 ```
-source <(switcher init shell)
+$ brew install danielfoehrkn/switch/switch
 ```
-Where `shell` is either bash, zsh or fish. 
 
-If you wish to source shell completion only, use:
-```
-source <(switcher completion shell)
-```
+Optionally, [install command completion](command_completion.md) and [verify the installation](#check-that-it-works).
 
-### Option 1b - MacPorts
+### Option 2 - MacPorts
+**NOTE**: `fish` users please follow [install via Github releases](#option-2---github-releases) as the shell script only works for `zsh` and `bash` shells.
 
 Mac users can also install both `switch.sh` and `switcher` from [MacPorts](https://www.macports.org)
 ```
 $ sudo port selfupdate
 $ sudo port install kubeswitch
 ```
 
-Source the `switch()` wrapper and autocompletion by adding this into `.bashrc`/`.zshrc`:
-```
-source <(switcher init shell)
-```
-Where `shell` is either bash, zsh or fish.
-
-### Option 2 - Manual Installation
+Optionally, [install command completion](command_completion.md) and [verify the installation](#check-that-it-works).
 
-#### From source
-
-```
-$ go get github.com/danielfoehrkn/kubeswitch
-```
-
-From the repository root run `make build-switcher`.
-This builds the binaries to `/hack/switch/`.
-Copy the build binary for your OS / Architecture to e.g. `/usr/local/bin`
-and source the switch script from `/hack/switch/switch.sh`.
-
-#### From Github releases
-
-Download the switch script and the switcher binary.
+### Option 2 - Github releases
 
+Download the switcher binary
 ```sh
 OS=linux                        # Pick the right os: linux, darwin (intel only)
 VERSION=0.7.0                   # Pick the current version.
 
 curl -L -o /usr/local/bin/switcher https://github.com/danielfoehrKn/kubeswitch/releases/download/${VERSION}/switcher_${OS}_amd64
 chmod +x /usr/local/bin/switcher
-
-curl -L -o  /usr/local/bin/switch.sh https://github.com/danielfoehrKn/kubeswitch/releases/download/${VERSION}/switch.sh
-chmod +x /usr/local/bin/switch.sh
 ```
 
-Source `switch.sh` in `.bashrc`/`.zsh` via:
+Next, follow [source the shell function](#source-the-shell-function).
 
-```sh
-source /usr/local/bin/switch.sh
+### Option 3 - From source
+
+```
+$ go get github.com/danielfoehrkn/kubeswitch
 ```
 
-## Set up finding kubeconfig files and contexts
+From the repository root run `make build-switcher`.
+This builds the binaries to `/hack/switch/`.
+Copy the build binary for your OS/Architecture to e.g. `/usr/local/bin`.
 
-If you installed kubeswitch correctly, you can run the command `switch`
-and should see the contexts it can find with its default configuration.
-The command is only available once you open a new terminal, in case you load
-`switch.sh` through `.bashrc`/`.zsh`. If you get the error
-`Error: you need to point kubeswitch to a kubeconfig file` or do not see all
-desired kubeconfig contexts that you want to choose from, follow
-[kubeconfig stores](kubeconfig_stores.md) for the configuration.
+Next, follow [source the shell function](#source-the-shell-function).
 
-## Command completion
+## Source the shell function
 
-The binary `switcher` comes with autocompletion for bash, zsh and fish and is installed automatically by sourcing `switcher init <shell>`, however to autocomplete on `switch` (and the alias `s`), add the following line in your shell configuration:
+Source the shell function which is used to call the `switcher` binary. 
+For `zsh/bash` the name of the shell function is `switch` and for `fish` its `kubeswitch`.
+Additionally, installs the command completion script.
+
+### Bash
 
-### Zsh
 ```sh
+echo 'source <(switcher init bash)' >> ~/.bashrc
+
+# optionally use alias `s` instead of `switch`
 alias s=switch
 compdef _switcher switch
 ```
-This enables autocompletion for both the `switch` function as well as the `s` alias.
+### Zsh
+```sh
+echo 'source <(switcher init zsh)' >> ~/.zshrc
 
+# optionally use alias `s` instead of `switch`
+alias s=switch
+compdef _switcher switch
+```
 ### Fish
-As fish shell have a built-in `switch` already, the `switcher init fish` installs a `kubeswitch` function instead. To autocomplete on `s` add the following to your configuration:
-
+Fish shell have a built-in `switch` function. Hence, differently from `zsh` shells, the kubeswitch function is called `kubeswitch`.
 ```sh
+echo 'switcher init fish | source' >> ~/.config/fish/config.fish
+
+# optionally use alias `s` instead of `kubeswitch`
 function s --wraps switcher
         kubeswitch $argv;
 end
 ```
 
-To install autocompletion without the `switch()` wrapper, take a [look here](command_completion.md).
+## Check that it works
 
-## Clean up temporary kubeconfig files
+If you installed kubeswitch correctly, you can run the command `switch` (zsh, bash) or `kubeswitch` (fish) or alternatively the alias `s` from the terminal.
+In case the terminal can't find the function, you might need to open another terminal or re-source your config file (`.zshrc`,`.bashrc`,...).
 
-To not alter the current shell session, `kubeswitch` does not spawn a new sub-shell.
-You need to configure a cleanup handler if you care to remove temporary kubeconfig files from `$HOME/.kube/.switch_tmp` when the shell session
-ends (close the terminal window, or `exit` is called).
-For `zsh`, please source [this script](/scripts/cleanup_handler_zsh.sh) from your `.zshrc` file.
+That should display the contexts the tool can find with the default configuration.
+The command is only available once you open a new terminal, in case you load
+`switch.sh` through `.bashrc`/`.zsh`. If you get the error
+`Error: you need to point kubeswitch to a kubeconfig file` or do not see all
+desired kubeconfig contexts that you want to choose from, follow
+[kubeconfig stores](kubeconfig_stores.md) for the configuration.