Merge pull request #941 from mchlumsky/feat/autocompletion

feat: add autocompletion support

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)"

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

setup.py

@@ -45,4 +45,5 @@ def get_version():
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
     ],
+    extras_require={"autocompletion": ["argcomplete>=1.10.0,<2"]},
 )