docs: Document completion, argparse update

Author: tony

CHANGES

@@ -17,7 +17,9 @@ $ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force
 
 ## vcspull v1.16.x (unreleased)
 
-- _Add your latest changes from PRs here_
+- Notes on upcoming releases will be added here
+
+<!-- Maintainers, insert changes / features for the next release here -->
 
 ## vcspull v1.15.2 (2022-10-08)
 

MIGRATION

@@ -21,7 +21,20 @@ well.
 
 ## Next release
 
-_Add migration notes here_
+_Notes on the upcoming release will be added here_
+
+<!-- Maintainers, insert changes / features for the next release here -->
+
+## vcspull 1.15.0 (2022-10-09)
+
+**Completions have changed** (#400)
+
+Completions now use a different tool: [shtab]. See the [completions page] for more information.
+
+If you were using earlier versions of vcspull (earlier than 1.15.0), you may need to uninstall the old completions, first.
+
+[completions page]: https://vcspull.git-pull.com/cli/completion.html
+[shtab]: https://docs.iterative.ai/shtab/
 
 <!---
 # vim: set filetype=markdown:

docs/cli/completion.md

@@ -0,0 +1,78 @@
+(completion)=
+
+(completions)=
+
+(cli-completions)=
+
+# Completions
+
+## vcspull 1.15+ (experimental)
+
+```{note}
+See the [shtab library's documentation on shell completion](https://docs.iterative.ai/shtab/use/#cli-usage) for the most up to date way of connecting completion for vcspull.
+```
+
+Provisional support for completions in vcspull 1.17+ are powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with vcspull**.
+
+```console
+$ pip install shtab --user
+```
+
+:::{tab} bash
+
+```bash
+shtab --shell=bash -u vcspull.cli.create_parser \
+  | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/VCSPULL
+```
+
+:::
+
+:::{tab} zsh
+
+```zsh
+shtab --shell=zsh -u vcspull.cli.create_parser \
+  | sudo tee /usr/local/share/zsh/site-functions/_VCSPULL
+```
+
+:::
+
+:::{tab} tcsh
+
+```zsh
+shtab --shell=tcsh -u vcspull.cli.create_parser \
+  | sudo tee /etc/profile.d/VCSPULL.completion.csh
+```
+
+:::
+
+## vcspull 0.9 to 1.14
+
+```{note}
+See the [click library's documentation on shell completion](https://click.palletsprojects.com/en/8.0.x/shell-completion/) for the most up to date way of connecting completion for vcspull.
+```
+
+vcspull 0.1 to 1.14 use [click](https://click.palletsprojects.com)'s completion:
+
+:::{tab} bash
+
+_~/.bashrc_:
+
+```bash
+
+eval "$(_VCSPULL_COMPLETE=bash_source vcspull)"
+
+```
+
+:::
+
+:::{tab} zsh
+
+_~/.zshrc_:
+
+```zsh
+
+eval "$(_VCSPULL_COMPLETE=zsh_source vcspull)"
+
+```
+
+:::

docs/cli/index.md

@@ -9,6 +9,13 @@
 sync
 ```
 
+```{toctree}
+:caption: Completion
+:maxdepth: 1
+
+completion
+```
+
 (cli-main)=
 
 (vcspull-main)=