nvim-plugins/nvim-lspconfig
1
0
Fork 0
mirror of https://github.com/neovim/nvim-lspconfig synced 2024-09-16 14:24:07 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: unverbose, mention "settings" param

Browse source 
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
This commit is contained in:
Justin M. Keyes 2022-06-13 01:12:52 -07:00
parent 86f9c29b40
commit 4f94bf5ba9
8 changed files with 112 additions and 164 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
.github/PULL_REQUEST_TEMPLATE/pull_request_template.md vendored
View file

@ -3,9 +3,3 @@ name: Pull Request
about: Submit a pull request
title: ''
---
<!--
If you want to make changes to the README.md, do so in scripts/README_template.md.
The CONFIG.md is auto-generated with all the options from the various LSP configuration;
do not edit it manually
-->

1
CONFIG.md
View file

@ -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.

2
CONTRIBUTING.md
View file

@ -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):

4
LICENSE.md
View file

@ -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

111
README.md
View file

@ -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 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.
```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.
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 (\<c-x\>\<c-o\>).
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\>).
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', '<space>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
}
```
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 <config_name>` 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 <client_id>` Defaults to stopping all buffer clients.
* `:LspRestart <client_id>` 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.

134
doc/lspconfig.txt
View file

@ -1,29 +1,14 @@
*lspconfig.txt* For Nvim version 0.6.1+ Last change: 2021 Nov 7
==============================================================================
TABLE OF CONTENTS *lspconfig-toc*
*lspconfig.txt* For Nvim version 0.7+
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|)
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.
nvim-lspconfig is not required to use the builtin Nvim |lsp| client, it is
just a convenience layer.
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.
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', '<space>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

11
lua/lspconfig/server_configurations/clangd.lua
View file

@ -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 = [[

7
scripts/README_template.md
View file

@ -1,8 +1,9 @@
# Configurations
<!-- *lspconfig-server-configurations* -->
<!-- *lspconfig-all* *lspconfig-server-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}}