Redesign Completion System

CHANGES.rst

@@ -90,6 +90,20 @@ Unreleased
     information about the object's structure that could be useful for a
     tool generating user-facing documentation. To get the structure of
     an entire CLI, use ``Context(cli).to_info_dict()``. :issue:`461`
+-   Redesign the shell completion system. :issue:`1484`, :pr:`1622`
+
+    -   Support Bash >= 4.4, Zsh, and Fish, with the ability for
+        extensions to add support for other shells.
+    -   Allow commands, groups, parameters, and types to override their
+        completions suggestions.
+    -   Groups complete the names commands were registered with, which
+        can differ from the name they were created with.
+    -   The ``autocompletion`` parameter for options and arguments is
+        renamed to ``shell_complete``. The function must take
+        ``ctx, param, incomplete``, must do matching rather than return
+        all values, and must return a list of strings or a list of
+        ``ShellComplete``. The old name and behavior is deprecated and
+        will be removed in 8.1.
 
 
 Version 7.1.2

docs/api.rst

@@ -169,6 +169,24 @@ Parsing
 .. autoclass:: OptionParser
    :members:
 
+
+Shell Completion
+----------------
+
+See :doc:`/shell-completion` for information about enabling and
+customizing Click's shell completion system.
+
+.. currentmodule:: click.shell_completion
+
+.. autoclass:: CompletionItem
+
+.. autoclass:: ShellComplete
+    :members:
+    :member-order: bysource
+
+.. autofunction:: add_completion_class
+
+
 Testing
 -------
 

docs/conf.py

@@ -22,6 +22,7 @@
     "sphinxcontrib.log_cabinet",
     "pallets_sphinx_themes",
     "sphinx_issues",
+    "sphinx_tabs.tabs",
 ]
 intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
 issues_github_path = "pallets/click"

docs/index.rst

@@ -79,7 +79,7 @@ usage patterns.
    advanced
    testing
    utils
-   bashcomplete
+   shell-completion
    exceptions
    unicode-support
    wincmd