Merge branch 'neovim:master' into bitbake

.github/workflows/comment-config-changes.yml

@@ -1,7 +1,7 @@
 name: "Check changes to config"
 on: [pull_request_target]
 jobs:
- close-changes:
+ check-config-changes:
  runs-on: ubuntu-latest
  permissions:
  pull-requests: write
@@ -15,6 +15,5 @@ jobs:
  ref: ${{ github.event.pull_request.head.sha }}
  - run: |
  if ! git diff origin/$GITHUB_BASE_REF...$(git branch --show-current) --exit-code -- doc/server_configurations.md doc/server_configurations.txt; then
- gh pr comment $PR_NUMBER --body 'Do not change `server_configurations.md` or `server_configurations.txt` directly as these are automatically generated. Edit the lua source file instead. See https://github.com/neovim/nvim-lspconfig/blob/master/CONTRIBUTING.md#generating-docs'
- exit 1
+ gh pr comment $PR_NUMBER --body 'Note that `server_configurations.md` or `server_configurations.txt` will be regenerated by the docgen CI process. Edit the Lua source file instead. For details on generating documentation, see: https://github.com/neovim/nvim-lspconfig/blob/master/CONTRIBUTING.md#generating-docs'
  fi

CONTRIBUTING.md

@@ -1,13 +1,12 @@
 ## Requirements
 
-- [Neovim](https://neovim.io/) 0.6 or later
-- Lint task requires [luacheck](https://github.com/luarocks/luacheck#installation) and [stylua](https://github.com/JohnnyMorganz/StyLua). If using nix, you can use `nix develop` to install these to a local nix shell.
+- [Link requirements](#Lint)
 - Documentation is generated by `scripts/docgen.lua`.
  - Only works on linux and macOS
 
 ## Scope of lspconfig
 
-The point of lspconfig is to provide the minimal configuration necessary for a server to act in compliance with the language server protocol. In general, if a server requires custom client-side commands or  off-spec handlers, then the server configuration should be added *without* those in lspconfig and receive a dedicated plugin such as nvim-jdtls, nvim-metals, etc.
+The point of lspconfig is to provide the minimal configuration necessary for a server to act in compliance with the language server protocol. In general, if a server requires custom client-side commands or off-spec handlers, then the server configuration should be added *without* those in lspconfig and receive a dedicated plugin such as nvim-jdtls, nvim-metals, etc.
 
 ## Pull requests (PRs)
 
@@ -107,10 +106,17 @@ with the commit body containing additional details.
 
 ## Lint
 
-PRs are checked with [luacheck](https://github.com/mpeterv/luacheck), [StyLua](https://github.com/JohnnyMorganz/StyLua) and [selene](https://github.com/Kampfkarren/selene). Please run the linter locally before submitting a PR:
+PRs are checked with the following software:
+- [luacheck](https://github.com/luarocks/luacheck#installation)
+- [stylua](https://github.com/JohnnyMorganz/StyLua).
+- [selene](https://github.com/Kampfkarren/selene)
+
+Please run the linter locally before submitting a PR:
 
  make lint
 
+If using nix, you can use `nix develop` to install these to a local nix shell.
+
 ## Generating docs
 
 GitHub Actions automatically generates `server_configurations.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config Lua file. Do not modify `server_configurations.md` directly.

README.md

@@ -4,7 +4,7 @@
 
 * **Do not file Nvim LSP client issues here.** The Nvim LSP client does not live here. This is only a collection of LSP configs.
 * If you found a bug in the Nvim LSP client, [report it at the Nvim core repo](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
-* These configs are **best-effort and unsupported.** See [contributions](#contributions).
+* These configs are **best-effort and supported by the community.** See [contributions](#contributions).
 
 See also `:help lspconfig`.
 
@@ -13,7 +13,12 @@ See also `:help lspconfig`.
 [![LuaRocks](https://img.shields.io/luarocks/v/neovim/nvim-lspconfig?logo=lua&color=purple)](https://luarocks.org/modules/neovim/nvim-lspconfig)
 
 * Requires neovim version 0.8 above. Update Nvim and nvim-lspconfig before reporting an issue.
-* Install nvim-lspconfig as a normal plugin through neovim builtin `packadd` or a plugin manager
+
+* Install nvim-lspconfig using builtin packages:
+
+ git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig
+
+* Alternatively, nvim-lspconfig can be installed using a 3rd party plugin manager (consult the documentation for your plugin manager for details).
 
 ## Quickstart
 
@@ -29,69 +34,58 @@ See also `:help lspconfig`.
  ```
  nvim main.py
  ```
-4. Run `:LspInfo` to see the status or to troubleshoot.
-5. See [Suggested configuration](#Suggested-configuration) to setup common mappings and omnifunc completion.
+4. Run `:checkhealth lsp` to see the status or to troubleshoot.
 
 See [server_configurations.md](doc/server_configurations.md) (`:help lspconfig-all` from Nvim) for the full list of configs, including installation instructions and additional, optional, customization suggestions for each language server. For servers that are not on your system path (e.g., `jdtls`, `elixirls`), you must manually add `cmd` to the `setup` parameter. Most language servers can be installed in less than a minute.
 
-## Suggested configuration
+## Configuration
+
+Nvim sets some default options whenever a buffer attaches to an LSP client. See [`:h lsp-config`][lsp-config] for more details. In particular, the following options are set:
+
+* [`'tagfunc'`][tagfunc]
+ - Enables "go to definition" capabilities using [`<C-]>`][tagjump] and other [tag commands][tag-commands].
+* [`'omnifunc'`][omnifunc]
+ - Enables (manual) omni mode completion with `<C-X><C-O>` in Insert mode. For *auto*completion, an [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required.
+* [`'formatexpr'`][formatexpr]
+ - Enables LSP formatting with [`gq`][gq].
+
+Nvim also maps `K` to [`vim.lsp.buf.hover()`][vim.lsp.buf.hover] in Normal mode.
+
+Nvim 0.10 and newer creates the following default maps unconditionally:
 
-nvim-lspconfig does not set keybindings or enable completion by default. The following example configuration provides suggested keymaps for the most commonly used language server functions, and manually triggered completion with omnifunc (\<c-x\>\<c-o\>).
+* `[d` and `]d` map to `vim.diagnostic.goto_prev()` and `vim.diagnostic.goto_next()` (respectively)
+* `<C-W>d` maps to `vim.diagnostic.open_float()`
+
+[lsp-config]: https://neovim.io/doc/user/lsp.html#lsp-config
+[tagfunc]: https://neovim.io/doc/user/tagsrch.html#tag-function
+[omnifunc]: https://neovim.io/doc/user/options.html#'omnifunc'
+[formatexpr]: https://neovim.io/doc/user/options.html#'formatexpr'
+[gq]: https://neovim.io/doc/user/change.html#gq
+[vim.lsp.buf.hover]: https://neovim.io/doc/user/lsp.html#vim.lsp.buf.hover()
+[tagjump]: https://neovim.io/doc/user/tagsrch.html#CTRL-%5D
+[tag-commands]: https://neovim.io/doc/user/tagsrch.html#tag-commands
+
+Further customization can be achieved using the [`LspAttach`][LspAttach] autocommand event.
+The [`LspDetach`][LspAttach] autocommand event can be used to "cleanup" mappings if a buffer becomes detached from an LSP server.
+See [`:h LspAttach`][LspAttach] and [`:h LspDetach`][LspDetach] for details and examples.
+See [`:h lsp-buf`][lsp-buf] for details on other LSP functions.
+
+[LspAttach]: https://neovim.io/doc/user/lsp.html#LspAttach
+[LspDetach]: https://neovim.io/doc/user/lsp.html#LspDetach
+[lsp-buf]: https://neovim.io/doc/user/lsp.html#lsp-buf
+
+Additional configuration options can be provided for each LSP server by passing arguments to the `setup` function. See `:h lspconfig-setup` for details. Example:
 
 ```lua
--- 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,
-})
 ```
 
-Manual, triggered completion is provided by Nvim's builtin omnifunc. For *auto*completion, a general purpose [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required.
-
 ## Troubleshooting
 
 If you have an issue, the first step is to reproduce with a [minimal configuration](https://github.com/neovim/nvim-lspconfig/blob/master/test/minimal_init.lua).
@@ -101,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:

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
@@ -473,64 +476,6 @@ contained in `:LspInfo`:
 - `:LspRestart <client_id>` restarts the client with the given client id, and
  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*