feat: add autocompletion support

3 files changed, 65 insertions, 0 deletions

diff --git a/docs/cli.rst b/docs/cli.rst
index 7b0993e..e87c6d1 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -271,3 +271,61 @@ command line. This is handy for values containing new lines for instance:
    It is obviously the best project around
    EOF
    $ gitlab project create --name SuperProject --description @/tmp/description
+
+Enabling shell autocompletion
+============================
+
+To get autocompletion, you'll need to install the package with the extra
+"autocompletion":
+
+.. code-block:: console
+
+    pip install python_gitlab[autocompletion]
+
+
+Add the appropriate command below to your shell's config file so that it is run on
+startup. You will likely have to restart or re-login for the autocompletion to
+start working.
+
+Bash
+----
+
+.. code-block:: console
+
+   eval "$(register-python-argcomplete gitlab)"
+
+tcsh
+----
+
+.. code-block:: console
+
+   eval `register-python-argcomplete --shell tcsh gitlab`
+
+fish
+----
+
+.. code-block:: console
+
+   register-python-argcomplete --shell fish gitlab | .
+
+Zsh
+---
+
+.. warning::
+
+    Zsh autocompletion support is broken right now in the argcomplete python
+    package. Perhaps it will be fixed in a future release of argcomplete at
+    which point the following instructions will enable autocompletion in zsh.
+
+To activate completions for zsh you need to have bashcompinit enabled in zsh:
+
+.. code-block:: console
+
+   autoload -U bashcompinit
+   bashcompinit
+
+Afterwards you can enable completion for gitlab:
+
+.. code-block:: console
+
+   eval "$(register-python-argcomplete gitlab)"
diff --git a/gitlab/cli.py b/gitlab/cli.py
index 26ea0c0..8fc30bc 100644
--- a/gitlab/cli.py
+++ b/gitlab/cli.py
@@ -172,6 +172,12 @@ def main():
 
     # Now we build the entire set of subcommands and do the complete parsing
     parser = _get_parser(cli_module)
+    try:
+        import argcomplete
+
+        argcomplete.autocomplete(parser)
+    except Exception:
+        pass
     args = parser.parse_args(sys.argv[1:])
 
     config_files = args.config_file
diff --git a/setup.py b/setup.py
index 7bea224..6f52ecc 100644
--- a/setup.py
+++ b/setup.py
@@ -45,4 +45,5 @@ setup(
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
     ],
+    extras_require={"autocompletion": ["argcomplete>=1.10.0,<2"]},
 )