From 4f94bf5ba90e97a9718e5a2eb57b0737e1bdd176 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 13 Jun 2022 01:12:52 -0700 Subject: [PATCH] docs: unverbose, mention "settings" param Problem: - The docs are verbose. - The "settings" param is not really clarified anywhere. Solution: - Mention the "settings" param in the README. - Tighten up the wording. - Remove the "Use a loop to conveniently call 'setup'..." advice in the docs. It confuses users and doesn't really save much code. - Start to reduce the scope of nvim-lspconfig. - For example, it is redundant for it to document general LSP things. Thus, the help section *lspconfig-lsp* was removed. closes #1951 --- .../pull_request_template.md | 6 - CONFIG.md | 1 - CONTRIBUTING.md | 2 +- LICENSE.md | 4 +- README.md | 113 +++++++-------- doc/lspconfig.txt | 136 +++++++----------- .../server_configurations/clangd.lua | 11 +- scripts/README_template.md | 7 +- 8 files changed, 114 insertions(+), 166 deletions(-) delete mode 100644 CONFIG.md diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 6e450d78fb..efb4f2b55d 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -3,9 +3,3 @@ name: Pull Request about: Submit a pull request title: '' --- - - diff --git a/CONFIG.md b/CONFIG.md deleted file mode 100644 index 6aac655658..0000000000 --- a/CONFIG.md +++ /dev/null @@ -1 +0,0 @@ -Notice: CONFIG.md was moved to [doc/server_configurations.md](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md). This notice will be removed after the release of neovim 0.6. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7eea3f74c6..e97d6591bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,7 +125,7 @@ PRs are checked with [luacheck](https://github.com/mpeterv/luacheck), [StyLua](h ## Generating docs -Github Actions automatically generates `server_configurations.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config (the lua file). Do not modify `server_configurations.md` directly. +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. To preview the generated `server_configurations.md` locally, run `scripts/docgen.lua` from `nvim` (from the project root): diff --git a/LICENSE.md b/LICENSE.md index be03814a20..04c0a3d54c 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,8 +1,8 @@ Copyright Neovim contributors. All rights reserved. -nvim-lsp is licensed under the terms of the Apache 2.0 license. +nvim-lspconfig is licensed under the terms of the Apache 2.0 license. -nvim-lsp's license follows: +nvim-lspconfig's license follows: ==== Apache License diff --git a/README.md b/README.md index b1a9097dd2..bd477349f6 100644 --- a/README.md +++ b/README.md @@ -10,47 +10,40 @@ See also `:help lspconfig`. ## Install -* Requires [Neovim v0.6.1](https://github.com/neovim/neovim/releases/tag/v0.6.1) or [Nightly](https://github.com/neovim/neovim/releases/tag/nightly). Update Neovim and 'lspconfig' before reporting an issue. - -* Install 'lspconfig' like any other Vim plugin, e.g. with [packer.nvim](https://github.com/wbthomason/packer.nvim): - - ```lua - local use = require('packer').use - require('packer').startup(function() - use 'wbthomason/packer.nvim' -- Package manager - use 'neovim/nvim-lspconfig' -- Collection of configurations for the built-in LSP client - end) - ``` +* Requires [Neovim 0.7](https://github.com/neovim/neovim/releases/tag/v0.6.1) or [Nightly](https://github.com/neovim/neovim/releases/tag/nightly). Update Nvim and nvim-lspconfig before reporting an issue. +* Install nvim-lspconfig like any other Vim plugin, e.g. with [packer.nvim](https://github.com/wbthomason/packer.nvim): + ```lua + local use = require('packer').use + require('packer').startup(function() + use 'wbthomason/packer.nvim' -- Package manager + use 'neovim/nvim-lspconfig' -- Configurations for Nvim LSP + end) + ``` ## Quickstart 1. Install a language server, e.g. [pyright](doc/server_configurations.md#pyright) - - ```bash - npm i -g pyright - ``` - + ```bash + npm i -g pyright + ``` 2. Add the language server setup to your init.lua. - - ```lua - require'lspconfig'.pyright.setup{} - ``` - -3. Launch neovim, the language server will now be attached and providing diagnostics (see `:LspInfo`) - - ``` - nvim main.py - ``` - -4. See [Keybindings and completion](#Keybindings-and-completion) for mapping useful functions and enabling omnifunc completion - -For a full list of servers, see [server_configurations.md](doc/server_configurations.md) or `:help lspconfig-server-configurations`. This document contains installation instructions and additional, optional, customization suggestions for each language server. For some servers that are not on your system path (e.g., `jdtls`, `elixirls`), you will be required to manually add `cmd` as an entry in the table passed to `setup`. Most language servers can be installed in less than a minute. + ```lua + require'lspconfig'.pyright.setup{} + ``` +3. Launch Nvim, the language server will attach and provide diagnostics. + ``` + nvim main.py + ``` +4. Run `:LspInfo` to see the status or to troubleshoot. +5. See [Keybindings and completion](#Keybindings-and-completion) to setup common mappings and omnifunc completion. + +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 -'lspconfig' does not map 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 (\\). +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 (\\). -Note: **you must pass the defined `on_attach` as an argument to every `setup {}` call** and **the keybindings in `on_attach` only take effect on buffers with an active language server**. +Note: you must pass the defined `on_attach` as an argument to **every `setup {}` call** and the keybindings in `on_attach` **only take effect on buffers with an active language server**. ```lua -- Mappings. @@ -87,36 +80,40 @@ local on_attach = function(client, bufnr) vim.keymap.set('n', 'f', vim.lsp.buf.formatting, bufopts) end --- Use a loop to conveniently call 'setup' on multiple servers and --- map buffer local keybindings when the language server attaches -local servers = { 'pyright', 'rust_analyzer', 'tsserver' } -for _, lsp in pairs(servers) do - require('lspconfig')[lsp].setup { +local lsp_flags = { + -- This is the default in Nvim 0.7+ + debounce_text_changes = 150, +} +require('lspconfig')['pyright'].setup{ + on_attach = on_attach, + flags = lsp_flags, +} +require('lspconfig')['tsserver'].setup{ + on_attach = on_attach, + flags = lsp_flags, +} +require('lspconfig')['rust_analyzer'].setup{ on_attach = on_attach, - flags = { - -- This will be the default in neovim 0.7+ - debounce_text_changes = 150, + flags = lsp_flags, + -- Server-specific settings... + settings = { + ["rust-analyzer"] = {} } - } -end +} ``` -Manual, triggered completion is provided by neovim's built-in omnifunc. For **auto**completion, a general purpose [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required. +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. -## Debugging +## Troubleshooting -If you have an issue with 'lspconfig', the first step is to reproduce with a [minimal configuration](https://github.com/neovim/nvim-lspconfig/blob/master/test/minimal_init.lua). +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). The most common reasons a language server does not start or attach are: -1. The language server is not installed. '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. - +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. - 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: @@ -132,19 +129,16 @@ Attempt to run the language server, and open the log with: ``` Most of the time, the reason for failure is present in the logs. -## Built-in commands +## Commands * `:LspInfo` shows the status of active and configured language servers. - -The following support tab-completion for all arguments: - * `:LspStart ` Start the requested server name. Will only successfully start if the command detects a root directory matching the current config. Pass `autostart = false` to your `.setup{}` call for a language server if you would like to launch clients solely with this command. Defaults to all servers matching current buffer filetype. * `:LspStop ` Defaults to stopping all buffer clients. * `:LspRestart ` Defaults to restarting all buffer clients. -## The wiki +## Wiki -Please see the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additional topics, including: +See the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additional topics, including: * [Automatic server installation](https://github.com/neovim/nvim-lspconfig/wiki/Installing-language-servers#automatically) * [Snippets support](https://github.com/neovim/nvim-lspconfig/wiki/Snippets) @@ -154,16 +148,11 @@ Please see the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additio ## Contributions If you are missing a language server on the list in [server_configurations.md](doc/server_configurations.md), contributing -a new configuration for it would be appreciated. You can follow these steps: +a new configuration for it helps others, especially if the server requires special setup. Follow these steps: 1. Read [CONTRIBUTING.md](CONTRIBUTING.md). - 2. Create a new file at `lua/lspconfig/server_configurations/SERVER_NAME.lua`. - - Copy an [existing config](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/server_configurations/) to get started. Most configs are simple. For an extensive example see [texlab.lua](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/server_configurations/texlab.lua). - 3. Ask questions on our [Discourse](https://neovim.discourse.group/c/7-category/7) or in the [Neovim Matrix room](https://app.element.io/#/room/#neovim:matrix.org). - -You can also help out by testing [PRs with the `needs-testing`](https://github.com/neovim/nvim-lspconfig/issues?q=is%3Apr+is%3Aopen+label%3Aneeds-testing) label that affect language servers you use regularly. diff --git a/doc/lspconfig.txt b/doc/lspconfig.txt index ed53be0875..3a79db0aad 100644 --- a/doc/lspconfig.txt +++ b/doc/lspconfig.txt @@ -1,29 +1,14 @@ -*lspconfig.txt* For Nvim version 0.6.1+ Last change: 2021 Nov 7 -============================================================================== -TABLE OF CONTENTS *lspconfig-toc* - -1. Introduction (|lspconfig|) -2. LSP overview (|lspconfig-lsp|) -3. Quickstart (|lspconfig-quickstart|) -4. Setup {} (|lspconfig-setup|) -5. Global defaults (|lspconfig-global-defaults|) -6. Server configurations (|lspconfig-configurations|) - 6a. Adding servers (|lspconfig-adding-servers|) -7. Root directories (|lspconfig-root-detection|) - 7a. Advanced detection (|lspconfig-root-advanced|) - 7b. Single file support (|lspconfig-single-file-support|) -8. Commands (|lspconfig-commands|) -9. Keybindings (|lspconfig-keybindings|) -10. Completion (|lspconfig-completion|) -11. Debugging (|lspconfig-debugging|) -12. Logging (|lspconfig-logging|) -13. Scope (|lspconfig-scope|) +*lspconfig.txt* For Nvim version 0.7+ + +nvim-lspconfig provides user-contributed configs for the Nvim |lsp| client. + + Type |gO| to see the table of contents. ============================================================================== INTRODUCTION *lspconfig* -`lspconfig` is a collection of community contributed configurations for the -built-in language server client in Neovim core. This plugin provides four +nvim-lspconfig is a collection of community-contributed configurations for the +built-in language server client in Nvim core. This plugin provides four primary functionalities: - default launch commands, initialization options, and settings for each @@ -35,33 +20,10 @@ primary functionalities: - utility commands such as LspInfo, LspStart, LspStop, and LspRestart for managing language server instances -`lspconfig` is not required to use the built-in client, it is only one front-end -interface for when a language server specific plugin is not available. - -See |lspconfig-server-configurations| by typing `K` over it for the complete -list of language servers configurations. - -============================================================================== -LSP OVERVIEW *lspconfig-lsp* - -Nvim supports the Language Server Protocol (LSP) via the built-in language -server client. LSP facilitates many features, some of which include: - -- go-to-definition -- find-references -- hover -- completion -- rename -- format -- refactor - -These features are implemented in Neovim core, not `lspconfig`. See `:help lsp` -for more details. +nvim-lspconfig is not required to use the builtin Nvim |lsp| client, it is +just a convenience layer. -NOTE: Feature availability depends on the implementation details of the -server. A server may implement only a subset of these features. Always -consult the server documentation before filing a bug report on a missing -feature. +See |lspconfig-all| for the complete list of language server configurations. ============================================================================== QUICKSTART *lspconfig-quickstart* @@ -73,12 +35,12 @@ QUICKSTART *lspconfig-quickstart* require'lspconfig'.clangd.setup{} < - create a new project, ensure that it contains a root marker which matches the - server requirements specified in |lspconfig-server-configurations|. + server requirements specified in |lspconfig-all|. - open a file within that project, such as `main.c`. - If you need more information about a server configuration, read the corresponding - entry in |lspconfig-server-configurations|. + entry in |lspconfig-all|. ============================================================================== THE SETUP METAMETHOD *lspconfig-setup* @@ -92,9 +54,8 @@ Using the default configuration for a server is simple: > require'lspconfig'.clangd.setup{} < -The available server names are listed in |lspconfig-server-configurations| and -match the server name in `config.SERVER_NAME` defined in each configuration's -source file. +The available server names are listed in |lspconfig-all| and match the server +name in `config.SERVER_NAME` defined in each configuration's source file. The purpose of `setup{}` is to wrap the call to Nvim's built-in `vim.lsp.start_client()` with an autocommand that automatically launch a @@ -269,8 +230,7 @@ The global defaults for all servers can be overridden by extending the ============================================================================== SERVER CONFIGURATIONS *lspconfig-configurations* -See |lspconfig-server-configurations| by typing `K` over it for the complete -list of language servers configurations. +See |lspconfig-all| for the complete list of language server configurations. While the `setup {}` function is the primary interface to `lspconfig`, for servers for which there is not a configuration, it is necessary to define a @@ -320,22 +280,18 @@ After you set `configs.SERVER_NAME` you can add arbitrary language-specific functions to it if necessary. Example: - > configs.texlab.buf_build = buf_build < ============================================================================== -ADDING NEW SERVERS *lspconfig-adding-servers* +ADDING NEW SERVERS *lspconfig-new* -The three steps for adding and enabling a new server configuration are: +The steps for adding and enabling a new server configuration are: -- load the `lspconfig` module (note that this is a stylistic choice) -> +1. load the `lspconfig` module (note that this is a stylistic choice) > local lspconfig = require 'lspconfig' < -- define the configuration - -> +2. define the configuration > local configs = require 'lspconfig.configs' -- Check if the config is already defined (useful when reloading this file) @@ -352,8 +308,7 @@ The three steps for adding and enabling a new server configuration are: } end -- call `setup()` to enable the FileType autocmd -> +3. call `setup()` to enable the FileType autocmd > lspconfig.foo_lsp.setup{} < ============================================================================== @@ -520,31 +475,36 @@ attached to a given buffer. vim.keymap.set('n', 'f', vim.lsp.buf.formatting, bufopts) end - -- Use a loop to conveniently call 'setup' on multiple servers and - -- map buffer local keybindings when the language server attaches - local servers = { 'pyright', 'rust_analyzer', 'tsserver' } - for _, lsp in pairs(servers) do - require('lspconfig')[lsp].setup { + local lsp_flags = { + -- This is the default in Nvim 0.7+ + debounce_text_changes = 150, + } + require('lspconfig')['pyright'].setup{ on_attach = on_attach, - flags = { - -- This will be the default in neovim 0.7+ - debounce_text_changes = 150, + flags = lsp_flags, + } + require('lspconfig')['tsserver'].setup{ + on_attach = on_attach, + flags = lsp_flags, + } + require('lspconfig')['rust_analyzer'].setup{ + on_attach = on_attach, + flags = lsp_flags, + -- Server-specific settings... + settings = { + ["rust-analyzer"] = {} } - } - end -< -Note: these keymappings are meant for illustration and override some -infrequently used default mappings. + } ============================================================================== COMPLETION SUPPORT *lspconfig-completion* Manually triggered completion can be provided by Nvim's built-in omnifunc. -See `:help omnifunc` for more details. +See |lsp-config|. -For autocompletion, Nvim does not offer built-in functionality at this time. -Consult the `lspconfig` wiki, which provides configuration examples for using a -completion plugin with the built-in client +For autocompletion, Nvim does not provide built-in functionality. Consult the +nvim-lspconfig wiki, which provides configuration examples for using +a completion plugin with the built-in client ============================================================================== DEBUGGING *lspconfig-debugging* @@ -557,17 +517,17 @@ is typically (in rough order): - a plugin - overrides in a user configuration - the built-in client in Nvim core -- `lspconfig` +- nvim-lspconfig The first step in debugging is to test with a minimal configuration (such as `../test/minimal_init.lua`). Historically, many users problems are due to plugins or misconfiguration. Should that fail, identifying which component is the culprit is challenging. -The following are the only categories of bugs that pertain to `lspconfig`. +The following are the only categories of bugs that pertain to nvim-lspconfig. - The root directory inferred for your project is wrong, or it should be - detected but is not due to a bug in the `lspconfig` path utilities. + detected but is not due to a bug in the nvim-lspconfig path utilities. - The server is launching, but you believe that the default settings, initialization options, or command arguments are suboptimal and should be replaced based on your understanding of the server documentation. @@ -577,14 +537,14 @@ tracker. All bugs pertaining to plugins should be reported to the respective plugin. All missing features in a language server should be reported to the upstream language server issue tracker. -For debugging `lspconfig` issues, the most common hurdles users face are: +For debugging nvim-lspconfig issues, the most common hurdles users face are: - The language server is not installed or is otherwise not executable. - `lspconfig` does not install language servers for you. Ensure the `cmd` + nvim-lspconfig does not install language servers for you. Ensure the `cmd` defined in `server_configurations.md` is executable from the command line. If the absolute path to the binary is not supplied in `cmd`, ensure it is on your PATH. - - No root detected. `lspconfig` is built around the concept of projects. See + - No root detected. nvim-lspconfig is built around the concept of projects. See |lspconfig-root-detection| for more details. Most of the time, initializing a git repo will suffice. - Misconfiguration. Often users will override `cmd`, `on_init`, or diff --git a/lua/lspconfig/server_configurations/clangd.lua b/lua/lspconfig/server_configurations/clangd.lua index 0dbe2cfdbb..83cfc56de1 100644 --- a/lua/lspconfig/server_configurations/clangd.lua +++ b/lua/lspconfig/server_configurations/clangd.lua @@ -61,9 +61,14 @@ return { description = [[ https://clangd.llvm.org/installation.html -**NOTE:** Clang >= 11 is recommended! See [this issue for more](https://github.com/neovim/nvim-lsp/issues/23). - -clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) specified as compile_commands.json, see https://clangd.llvm.org/installation#compile_commandsjson +- **NOTE:** Clang >= 11 is recommended! See [#23](https://github.com/neovim/nvim-lsp/issues/23). +- If `compile_commands.json` lives in a build directory, you should + symlink it to the root of your source tree. + ``` + ln -s ~/myproject/compile_commands.json ~/myproject/build/ + ``` +- clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) + specified as compile_commands.json, see https://clangd.llvm.org/installation#compile_commandsjson ]], default_config = { root_dir = [[ diff --git a/scripts/README_template.md b/scripts/README_template.md index 3a9baeaab3..1339c50259 100644 --- a/scripts/README_template.md +++ b/scripts/README_template.md @@ -1,8 +1,9 @@ # Configurations - + -The following LSP configs are included. This documentation is autogenerated from the lua files. Follow a link to find documentation for -that config. This file is accessible in neovim via `:help lspconfig-server-configurations` +LSP configs provided by nvim-lspconfig are listed below. This documentation is +autogenerated from the Lua files. You can view this file in Nvim by running +`:help lspconfig-all`. {{implemented_servers_list}}