docs: delete lspconfig-keybindings section (#3175)

This section is way too verbose and encourages sloppy copy-pasting. Nvim
already ships help documentation for configuring the LSP client, so
instead of duplicating that information, point users toward upstream
docs instead.

2 files changed, 15 insertions, 70 deletions

diff --git a/README.md b/README.md
index 32c31f5e..8ddc5678 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ The most common reasons a language server does not start or attach are:
 1. The language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the `cmd` defined in each server's Lua module from the command line and see that the language server starts. If the `cmd` is an executable name instead of an absolute path to the executable, ensure it is on your path.
 2. Missing filetype plugins. Certain languages are not detecting by vim/neovim because they have not yet been added to the filetype detection system. Ensure `:set ft?` shows the filetype and not an empty value.
 3. Not triggering root detection. **Some** language servers will only start if it is opened in a directory, or child directory, containing a file which signals the *root* of the project. Most of the time, this is a `.git` folder, but each server defines the root config in the lua file. See [server_configurations.md](doc/server_configurations.md) or the source for the list of root directories.
-4. You must pass `on_attach` and `capabilities` for **each** `setup {}` if you want these to take effect.
+4. You must pass `capabilities` for **each** `setup {}` if you want these to take effect.
 5. **Do not call `setup {}` twice for the same server**. The second call to `setup {}` will overwrite the first.
 
 Before reporting a bug, check your logs and the output of `:LspInfo`. Add the following to your init.vim to enable logging:
diff --git a/doc/lspconfig.txt b/doc/lspconfig.txt
index 50a8f9d8..ef5c1803 100644
--- a/doc/lspconfig.txt
+++ b/doc/lspconfig.txt
@@ -21,7 +21,7 @@ primary functionalities:
    managing language server instances
 
 nvim-lspconfig is not required to use the builtin Nvim |lsp| client, it is
-just a convenience layer.
+just a convenience layer. See |lsp-quickstart|.
 
 See |lspconfig-all| for the complete list of language server configurations.
 
@@ -169,10 +169,11 @@ passed overrides to `setup {}` are:
   Callback invoked by Nvim's built-in client when attaching a buffer to a
   language server. Often used to set Nvim (buffer or global) options or to
   override the Nvim client properties (`server_capabilities`) after a
-  language server attaches. Most commonly used for settings buffer
-  local keybindings. See |lspconfig-keybindings| for a usage example.
+  language server attaches.
 
-- {settings} `table <string, string|table|bool>`  
+  Prefer using an |LspAttach| autocommand handler instead.
+
+- {settings} `table <string, string|table|bool>`
 
   The `settings` table is sent after initialization via a
   `workspace/didChangeConfiguration` notification from the Nvim client to
@@ -284,7 +285,8 @@ rest are either array values which will be formed into flags for the command,
 or special keys like `description`.
 
 Warning: Commands is deprecated and will be removed in future releases.
-It is recommended to use `vim.api.nvim_create_user_command()` instead in an `on_attach` function.
+It is recommended to use `vim.api.nvim_create_user_command()` instead in an
+|LspAttach| autocommand handler.
 
 Example:
 >
@@ -296,15 +298,16 @@ Example:
     vim.lsp.buf.execute_command(params)
   end
 
-  local on_attach = function(client, bufnr)
-    if client.name == "pyright" then
-      vim.api.nvim_create_user_command("PyrightOrganizeImports", organize_imports, {desc = 'Organize Imports'})
+  vim.api.nvim_create_autocmd('LspAttach', {
+    callback = function(ev)
+      local client = vim.lsp.get_client_by_id(ev.data.client_id)
+      if client.name == "pyright" then
+        vim.api.nvim_create_user_command("PyrightOrganizeImports", organize_imports, {desc = 'Organize Imports'})
+      end
     end
   end
 
-  require("lspconfig")['pyright'].setup({
-    on_attach = on_attach
-  })
+  require("lspconfig")['pyright'].setup{}
 <
 
 The `configs.__newindex` metamethod consumes the config definition and returns
@@ -474,64 +477,6 @@ contained in `:LspInfo`:
   will attempt to reattach to all previously attached buffers.
 
 ==============================================================================
-EXAMPLE KEYBINDINGS                                      *lspconfig-keybindings*
-
-`lspconfig`, and the core client, do not map any keybindings by default. The
-following is an example Lua block which demonstrates how to leverage the
-`LspAttach` (Nvim 0.8+) autocommand to apply keybindings after a language
-server has attached to a given buffer.
->
-  -- Setup language servers.
-  local lspconfig = require('lspconfig')
-  lspconfig.pyright.setup {}
-  lspconfig.tsserver.setup {}
-  lspconfig.rust_analyzer.setup {
-    -- Server-specific settings. See `:help lspconfig-setup`
-    settings = {
-      ['rust-analyzer'] = {},
-    },
-  }
-
-
-  -- Global mappings.
-  -- See `:help vim.diagnostic.*` for documentation on any of the below functions
-  vim.keymap.set('n', '<space>e', vim.diagnostic.open_float)
-  vim.keymap.set('n', '[d', vim.diagnostic.goto_prev)
-  vim.keymap.set('n', ']d', vim.diagnostic.goto_next)
-  vim.keymap.set('n', '<space>q', vim.diagnostic.setloclist)
-
-  -- Use LspAttach autocommand to only map the following keys
-  -- after the language server attaches to the current buffer
-  vim.api.nvim_create_autocmd('LspAttach', {
-    group = vim.api.nvim_create_augroup('UserLspConfig', {}),
-    callback = function(ev)
-      -- Enable completion triggered by <c-x><c-o>
-      vim.bo[ev.buf].omnifunc = 'v:lua.vim.lsp.omnifunc'
-
-      -- Buffer local mappings.
-      -- See `:help vim.lsp.*` for documentation on any of the below functions
-      local opts = { buffer = ev.buf }
-      vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, opts)
-      vim.keymap.set('n', 'gd', vim.lsp.buf.definition, opts)
-      vim.keymap.set('n', 'K', vim.lsp.buf.hover, opts)
-      vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, opts)
-      vim.keymap.set('n', '<C-k>', vim.lsp.buf.signature_help, opts)
-      vim.keymap.set('n', '<space>wa', vim.lsp.buf.add_workspace_folder, opts)
-      vim.keymap.set('n', '<space>wr', vim.lsp.buf.remove_workspace_folder, opts)
-      vim.keymap.set('n', '<space>wl', function()
-        print(vim.inspect(vim.lsp.buf.list_workspace_folders()))
-      end, opts)
-      vim.keymap.set('n', '<space>D', vim.lsp.buf.type_definition, opts)
-      vim.keymap.set('n', '<space>rn', vim.lsp.buf.rename, opts)
-      vim.keymap.set({ 'n', 'v' }, '<space>ca', vim.lsp.buf.code_action, opts)
-      vim.keymap.set('n', 'gr', vim.lsp.buf.references, opts)
-      vim.keymap.set('n', '<space>f', function()
-        vim.lsp.buf.format { async = true }
-      end, opts)
-    end,
-  })
-
-==============================================================================
 COMPLETION SUPPORT                                        *lspconfig-completion*
 
 Manually triggered completion can be provided by Nvim's built-in omnifunc.