RepoMirrors/nvim-lspconfig
1
0
Fork 0
mirror of https://github.com/neovim/nvim-lspconfig synced 2025-03-11 04:27:36 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: documentation overhaul (#1384)

Browse Source 
* remove automated generation of vimdoc + ci
* unify ADVANCED_README.md and vimdoc
* rename CONFIGS.md to server_configurations.md, move into doc folder
* move CONTRIBUTING.md to .github folder
This commit is contained in:
Michael Lingelbach 2021-11-09 09:53:21 -08:00 committed by GitHub
parent 3b20930937
commit 3d85ff447d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 8444 additions and 8331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CONTRIBUTING.md → .github/CONTRIBUTING.md vendored
View File

@ -80,9 +80,9 @@ PRs are checked with Luacheck and stylua. Please run the linter locally before s
## Generating docs
Github Actions automatically generates the `CONFIG.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config (the lua file). Do not modify `CONFIG.md` directly.
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.
To preview the generated `CONFIG.md` locally, run `scripts/docgen.lua` from
To preview the generated `server_configurations.md` locally, run `scripts/docgen.lua` from
`nvim` (from the project root):
nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'

41
.github/workflows/docgen.yml vendored
View File

@ -30,44 +30,3 @@ jobs:
git add CONFIG.md
# Only commit and push if we have changes
git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push)
vimdocgen:
needs: docgen
runs-on: [ubuntu-latest]
permissions:
contents: write
steps:
- uses: actions/checkout@v2
- uses: rhysd/action-setup-vim@v1
with:
neovim: true
version: nightly
- name: Install plugins
run: |
mkdir -p ~/.local/share/nvim/site/pack/vendor/start
git clone --depth 1 https://github.com/mjlbach/babelfish.nvim ~/.local/share/nvim/site/pack/vendor/start/babelfish.nvim
git clone --depth 1 https://github.com/nvim-treesitter/nvim-treesitter ~/.local/share/nvim/site/pack/vendor/start/nvim-treesitter
ln -s $(pwd) ~/.local/share/nvim/site/pack/vendor/start
- name: Build parser
run: |
export PACKPATH=$HOME/.local/share/nvim/site
nvim -u ~/.local/share/nvim/site/pack/vendor/start/babelfish.nvim/scripts/init.lua --headless -c 'TSInstallSync markdown' -c 'qa'
- name: Generating docs
run: |
export PATH="${PWD}/build/:${PATH}"
export PACKPATH=$HOME/.local/share/nvim/site
nvim -u ~/.local/share/nvim/site/pack/vendor/start/babelfish.nvim/scripts/init.lua --headless -c 'luafile ./scripts/vimdocgen.lua' -c 'qa'
- name: Commit changes
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COMMIT_MSG: |
docs: update README.md
skip-checks: true
run: |
git config user.email "actions@github"
git config user.name "Github Actions"
git remote set-url origin https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
git pull
git add doc/lspconfig.txt
# Only commit and push if we have changes
git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push origin HEAD:${GITHUB_REF})

14
.mergify.yml
View File

@ -1,8 +1,8 @@
pull_request_rules:
- name: disallow changing a file
conditions:
- files=CONFIG.md
actions:
close:
comment:
message: "CONFIG.md is auto-generated: edit the lua source file instead (and re-read the PR template)."
# - name: disallow changing a file
# conditions:
# - files=CONFIG.md
# actions:
# close:
# comment:
# message: "CONFIG.md is auto-generated: edit the lua source file instead (and re-read the PR template)."

215
ADVANCED_README.md
View File

@ -1,215 +0,0 @@
## Advanced usage
**All provided examples are in Lua,** see `:help :lua-heredoc` to use Lua from your init.vim,
or the quickstart above for an example of a lua heredoc.
Each config provides a `setup()` function to initialize the server with reasonable default
initialization options and settings, as well as some server-specific commands. This is
invoked in the following form, where `<server>` corresponds to the language server name
in [CONFIG.md](CONFIG.md).
`setup()` takes optional arguments <config>, each of which overrides the respective
part of the default configuration. The allowed arguments are detailed [below](#setup-function).
```lua
require'lspconfig'.<server>.setup{<config>}
```
### The structure of `config`
The `configs` module is a singleton where configs are defined. In `vim.validate`
parlance here is the "spec":
configs.SERVER_NAME = {
default_config = {'t'};
on_new_config = {'f', true};
on_attach = {'f', true};
commands = {'t', true};
docs = {'t', true};
}
docs = {
description = {'s', true};
default_config = {'t', true};
}
- Keys in `docs.default_config` match those of
`configs.SERVER_NAME.default_config`, and can be used to specify custom
documentation. This is useful for functions, whose docs cannot be easily
auto-generated.
- `commands` is a map of `name:definition` key:value pairs, where `definition`
is a list whose first value is a function implementing the command and the
rest are either array values which will be formed into flags for the command
or special keys like `description`. Example:
```
commands = {
TexlabBuild = {
function()
buf_build(0)
end;
"-range";
description = "Build the current buffer";
};
};
```
The `configs.__newindex` metamethod consumes the config definition and returns
an object with a `setup()` method, to be invoked by users:
require'lspconfig'.SERVER_NAME.setup{}
After you set `configs.SERVER_NAME` you can add arbitrary language-specific
functions to it if necessary.
Example:
configs.texlab.buf_build = buf_build
### Example: using a default config
To use the defaults, just call `setup()` with an empty `config` parameter.
For the `gopls` config, that would be:
```lua
require'lspconfig'.gopls.setup{}
```
### Example: override some defaults
To set some config properties at `setup()`, specify their keys. For example to
change how the "project root" is found, set the `root_dir` key:
```lua
local lspconfig = require'lspconfig'
lspconfig.gopls.setup{
root_dir = lspconfig.util.root_pattern('.git');
}
```
The [documentation](CONFIG.md) for each config lists default values and
additional optional properties. For a more complicated example overriding
the `name`, `log_level`, `message_level`, and `settings` of texlab:
```lua
local lspconfig = require'lspconfig'
lspconfig.texlab.setup{
name = 'texlab_fancy';
settings = {
latex = {
build = {
onSave = true;
}
}
}
}
```
### Example: custom config
To configure a custom/private server, just
1. load the lspconfig module: `local lspconfig = require('lspconfig')`,
2. Define the config: `lspconfig.configs.foo_lsp = { … }`
3. Call `setup()`: `lspconfig.foo_lsp.setup{}`
```lua
local lspconfig = require'lspconfig'
local configs = require'lspconfig/configs'
-- Check if it's already defined for when reloading this file.
if not lspconfig.foo_lsp then
configs.foo_lsp = {
default_config = {
cmd = {'/home/ashkan/works/3rd/lua-language-server/run.sh'};
filetypes = {'lua'};
root_dir = function(fname)
return lspconfig.util.find_git_ancestor(fname) or vim.loop.os_homedir()
end;
settings = {};
};
}
end
lspconfig.foo_lsp.setup{}
```
### Example: override default config for all servers
If you want to change default configs for all servers, you can override default_config like this. In this example, we additionally add a check for log_level and message_level which can be passed to the server to control the verbosity of "window/logMessage".
```lua
local lspconfig = require'lspconfig'
lspconfig.util.default_config = vim.tbl_extend(
"force",
lspconfig.util.default_config,
{
autostart = false,
handlers = {
["window/logMessage"] = function(err, method, params, client_id)
if params and params.type <= vim.lsp.protocol.MessageType.Log then
vim.lsp.handlers["window/logMessage"](err, method, params, client_id)
end
end;
["window/showMessage"] = function(err, method, params, client_id)
if params and params.type <= vim.lsp.protocol.MessageType.Warning.Error then
vim.lsp.handlers["window/showMessage"](err, method, params, client_id)
end
end;
}
}
)
```
## setup() function
setup() extends the arguments listed in `:help vim.lsp.start_client()`. **In addition to all of the arguments defined for start_client**, the following key/value pairs can be passed to the setup function:
```
lspconfig.SERVER.setup{config}
The `config` parameter has the same shape as that of
|vim.lsp.start_client()|, with these additions:
{root_dir}
Required for some servers, optional for others.
Function of the form `function(filename, bufnr)`.
Called on new candidate buffers being attached-to.
Returns either a root_dir or nil.
If a root_dir is returned, then this file will also be attached. You
can optionally use {filetype} to help pre-filter by filetype.
If a root_dir is returned which is unique from any previously returned
root_dir, a new server will be spawned with that root_dir.
If nil is returned, the buffer is skipped.
See |lspconfig.util.search_ancestors()| and the functions which use it:
- |lspconfig.util.root_pattern(pattern1, pattern2...)| is a variadic function which
takes string patterns as arguments, and finds an ancestor
which contains one of the files matching the pattern.
Each pattern can be a specific filename, such as ".git", or a glob.
See `:help glob` for allowed patterns. This is equivalent to
coc.nvim's "rootPatterns"
- Related utilities for common tools:
- |lspconfig.util.find_git_root()|
- |lspconfig.util.find_node_modules_root()|
- |lspconfig.util.find_package_json_root()|
{name}
Defaults to the server's name.
{filetypes}
Set of filetypes to filter for consideration by {root_dir}.
May be empty.
Server may specify a default value.
{autostart}
Whether to automatically start a language server when a matching filetype is detected.
Defaults to true.
{on_new_config}
`function(new_config, new_root_dir)` will be executed after a new configuration has been
created as a result of {root_dir} returning a unique value. You can use this
as an opportunity to further modify the new_config or use it before it is
sent to |vim.lsp.start_client()|. If you set a custom `on_new_config`, ensure that
you read the original `on_new_config` defined in lspconfig, as many server configurations
leverage this to modify `cmd` at runtime, and this functionality should likely be duplicated
in your override.
```

7842
CONFIG.md
View File

File diff suppressed because it is too large Load Diff

14
README.md
View File

@ -1,6 +1,6 @@
# nvim-lspconfig
A [collection of common configurations](https://github.com/neovim/nvim-lspconfig/blob/master/CONFIG.md) for Neovim's built-in [language server client](https://neovim.io/doc/user/lsp.html).
A [collection of common configurations](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md) for Neovim's built-in [language server client](https://neovim.io/doc/user/lsp.html).
This plugin allows for declaratively configuring, launching, and initializing language servers you have installed on your system. Language server configurations are community-maintained.
@ -32,13 +32,13 @@ These features are not implemented in this repo, but in Neovim core. See `:help
## Quickstart
1. Install a language server, e.g. [pyright](CONFIG.md#pyright)
1. Install a language server, e.g. [pyright](doc/server_configurations.md#pyright)
```bash
npm i -g pyright
```
2. Add the language server setup to your init.vim. The server name must match those found in the table of contents in [CONFIG.md](CONFIG.md)
2. Add the language server setup to your init.vim. The server name must match those found in the table of contents in [server_configurations.md](server_configurations.md)
```lua
lua << EOF
@ -65,7 +65,7 @@ These features are not implemented in this repo, but in Neovim core. See `:help
## Automatically launching language servers
In order to automatically launch a language server, lspconfig searches up the directory tree from your current buffer to find a file matching the `root_dir` pattern defined in each server's configuration. For [pyright](CONFIG.md#pyright), this is any directory containing ".git", "setup.py", "setup.cfg", "pyproject.toml", or "requirements.txt").
In order to automatically launch a language server, lspconfig searches up the directory tree from your current buffer to find a file matching the `root_dir` pattern defined in each server's configuration. For [pyright](doc/server_configurations.md#pyright), this is any directory containing ".git", "setup.py", "setup.cfg", "pyproject.toml", or "requirements.txt").
Language servers require each project to have a `root` in order to provide completion and search across symbols that may not be defined in your current file, and to avoid having to index your entire filesystem on each startup.
@ -79,7 +79,7 @@ require'lspconfig'.rust_analyzer.setup{}
EOF
```
For a full list of servers, see [CONFIG.md](CONFIG.md). This document contains installation instructions and additional, optional customization suggestions for each language server. For some servers that are not on your system path (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.
For a full list of servers, see [server_configurations.md](doc/server_configurations.md). This document contains installation instructions and additional, optional customization suggestions for each language server. For some servers that are not on your system path (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.
## Keybindings and completion
@ -147,7 +147,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, ensure it is on your path.
2. Not triggering root detection. The language server 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 [CONFIG.md](CONFIG.md) or the source for the list of root directories.
2. Not triggering root detection. The language server 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](server_configurations.md) or the source for the list of root directories.
3. Misconfiguration. You must pass `on_attach` and `capabilities` for **each** `setup {}` if you want these to take effect. You must also **not call `setup {}` twice for the same server**. The second call to `setup {}` will overwrite the first.
@ -191,7 +191,7 @@ In order for neovim to launch certain executables on Windows, it must append `.c
## Contributions
If you are missing a language server on the list in [CONFIG.md](CONFIG.md), contributing
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:
1. Read [CONTRIBUTING.md](CONTRIBUTING.md).

776
doc/lspconfig.txt
View File

@ -1,19 +1,53 @@
*lspconfig.txt* For Nvim version 0.5.1+ Last change: 2021 Nov 7
==============================================================================
1. nvim-lspconfig *lspconfig-nvim-lspconfig*
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|)
6b. Index (|lspconfig-index|)
7. Root directories (|lspconfig-root-directories|)
6a. Root composition (|lspconfig-root-composition|)
6b. 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|)
A [collection of common configurations](https://github.com/neovim/nvim-lspconfig/blob/master/CONFIG.md)
for Neovim's built-in [language server client](https://neovim.io/doc/user/lsp.html).
This plugin allows for declaratively configuring, launching, and initializing
language servers you have installed on your system. Language server
configurations are community-maintained.
==============================================================================
2. LSP overview *lspconfig-lsp-overview*
INTRODUCTION *lspconfig*
`lspconfig` is a collection of community contributed configurations for the
built-in language server client in Neovim core. This plugin provides four
primary functionalities:
- default launch commands, initialization options, and settings for each
server
- a root directory resolver which attempts to detect the root of your project
- an autocommand mapping that either launches a new language server or
attempts to attach a language server to each opened buffer if it falls
under a tracked project
- 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-index| for the reference to the complete list of language
servers.
==============================================================================
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:
Neovim supports the Language Server Protocol (LSP), which means it acts as a
client to language servers and includes a Lua framework `vim.lsp` for building
enhanced LSP tools. LSP facilitates features like:
- go-to-definition
- find-references
- hover
@ -21,222 +55,586 @@ enhanced LSP tools. LSP facilitates features like:
- rename
- format
- refactor
Neovim provides an interface for all of these features, and the language server
client is designed to be highly extensible to allow plugins to integrate
language server features which are not yet present in Neovim core such as [**auto**-completion](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion)
(as opposed to manual completion with omnifunc) and [snippet integration](https://github.com/neovim/nvim-lspconfig/wiki/Snippets).
These features are not implemented in this repo, but in Neovim core. See `:help
lsp` for more details.
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.
==============================================================================
3. Install *lspconfig-install*
QUICKSTART *lspconfig-quickstart*
- ensure the server is installed and executable from the command line
* Requires [Neovim v0.5.0](https://github.com/neovim/neovim/releases/tag/v0.5.0) or [Nightly](https://github.com/neovim/neovim/releases/tag/nightly). Update Neovim and nvim-lspconfig before reporting an issue.
* Install nvim-lspconfig like any other Vim plugin, e.g. with [vim-plug](https://github.com/junegunn/vim-plug):
- enable the server in your Neovim configuration (Lua example):
>
require'lspconfig'.clangd.setup{}
<
- create a new project, ensure it contains a root marker which matches the
server requirements specified in `server_configurations.md`.
- open a file within that project, such as `main.c`.
```vim
Plug 'neovim/nvim-lspconfig'
```
==============================================================================
4. Quickstart *lspconfig-quickstart*
THE SETUP METAMETHOD *lspconfig-setup*
`lspconfig` consists of a collection of language server configurations. Each
configuration exposes a `setup {}` metamethod which makes it easy to directly
use the default configuration or selectively override the defaults.
`setup {}` is the primary interface by which users interact with `lspconfig`.
Using the default configuration for a server is simple:
>
require'lspconfig'.clangd.setup{}
<
The available server names are listed in `server_configurations.md` 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
language server.
This autocommand calls `start_client()` or `vim.lsp.buf_attach_client()`
depending on whether the current file belongs to a project with a currently
running client. See |lspconfig-root-directory| for more details.
The `setup{}` function takes a table which contains a superset of the keys
listed in `:help vim.lsp.start_client()` with the following unique entries:
- {root_dir}
`function(filename, bufnr)`
Returns either a filepath (string) or nil. The language server will only
start if the function returns a filepath.
If a root directory (string) is returned which is unique from any
previously returned root_dir, a new server will be spawned with that
root directory. See |lspconfig-root-directory| for more details
- {name}
`string`
Defaults to the server's name (`clangd`, `pyright`, etc.).
- {filetypes}
`list[string] | nil`
Set of filetypes for which to attempt to resolve {root_dir}.
May be empty, or server may specify a default value.
- {autostart}
`bool` (default: true)
Controls if the `FileType` autocommand that launches a language server is
created. If `false`, allows for deferring language servers until manually
launched with `:LspStart` (|lspconfig-commands|).
- {on_new_config}
`function(new_config, new_root_dir)`
Function executed after a root directory is detected. This is used to
modify the server configuration (including `cmd` itself). Most commonly,
this is used to inject additional arguments into `cmd`.
If overriding `on_new_config`, ensure that you read the
`on_new_config` defined in the source file of the default configuration
in `lspconfig`. The original `on_new_config` snippet for a given server
should likely be included in your new override. Some configurations
use `on_new_config` to dynamically set or modify `cmd`.
Note: all entries passed to `setup {}` override the entry in the default
configuration. There is no composition.
All `config` elements described in `:help vim.lsp.start_client()` can
additionally be overridden via the `setup {}` call. The most commonly
passed overrides to `setup {}` are:
- {capabilities} `table <string, string|table|bool|function>`
a table which represents the neovim client capabilities. Useful for
broadcasting to the server additional functionality (snippets, off-protocol
features) provided by plugins.
- {cmd} `list[string]`
a list where each entry corresponds to the blankspace delimited part of
the command that launches the server. The first entry is the binary used
to run the language server. Additional entries are passed as arguments.
The equivalent `cmd` for:
>
foo --bar baz
<
is:
>
{'foo', '--bar', 'baz}
<
- {handlers} `list[functions]`
a list of handlers which override the function used to process a response
from a given language server. Applied only to the server referenced by
setup. See |lsp-handler|.
- {init_options} `table <string, string|table|bool>`
a table passed during the initialization notification after launching
a language server. Equivalent to the `initializationOptions` field found
in `InitializeParams` in the LSP specification.
See upstream server documentation for available initialization
options.
- {on_attach} `function(client, bufnr)`
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 (`resolved_capabilities`) after a
language server attaches. Most commonly used for settings buffer
local keybindings. See |lspconfig-keybindings| for a usage example.
- {settings} `table <string, string|table|bool>`
The `settings` table is sent in `on_init` via a
`workspace/didChangeConfiguration` notification from the Nvim client to
the language server. These settings allow a user to change optional runtime
settings of the language server.
The script that automatically generates `server_configurations.md` converts
the `package.json` referenced in a server configuration source file
into a list of optional settings listed in `server_configurations.md`.
As an example, to set the following settings found in the pyright
documentation:
`pyright.disableLanguageServices`: `boolean`
`pyright.disableOrganizeImports`: `boolean`
Nested keys need to be translated into a nested table and passed to
the settings field in `setup {}` as follows:
>
require('lspconfig').pyright.setup{
settings = {
pyright = {
disableLanguageServices = true,
disableOrganizeImports = true,
}
}
}
<
Note that the autogenerated settings occasionally include VS code specific
settings. If a setting is not respected by a language server, consult
upstream docuemntation.
1. Install a language server, e.g. [pyright](CONFIG.md#pyright)
```bash
npm i -g pyright
```
2. Add the language server setup to your init.vim. The server name must match those found in the table of contents in [CONFIG.md](CONFIG.md)
```lua
lua << EOF
require'lspconfig'.pyright.setup{}
EOF
```
3. Create a project, this project must contain a file matching the root directory trigger. See [Automatically launching language servers](#Automatically-launching-language-servers) for additional info.
```bash
mkdir test_python_project
cd test_python_project
git init
touch main.py
```
4. Launch neovim, the language server will now be attached and providing diagnostics (see `:LspInfo`)
```
nvim main.py
```
5. See [Keybindings and completion](#Keybindings-and-completion) for mapping useful functions and enabling omnifunc completion
==============================================================================
5. Automatically launching language servers*lspconfig-automatically-launching-language-servers*
OVERRIDING GLOBAL DEFAULTS *lspconfig-override-global-defaults*
The global defaults for all servers can be overridden by extending the
`default_config` table.
>
local lspconfig = require'lspconfig'
lspconfig.util.default_config = vim.tbl_extend(
"force",
lspconfig.util.default_config,
{
autostart = false,
handlers = {
["window/logMessage"] = function(err, method, params, client_id)
if params and params.type <= vim.lsp.protocol.MessageType.Log then
vim.lsp.handlers["window/logMessage"](err, method, params, client_id)
end
end;
["window/showMessage"] = function(err, method, params, client_id)
if params and params.type <= vim.lsp.protocol.MessageType.Warning.Error then
vim.lsp.handlers["window/showMessage"](err, method, params, client_id)
end
end;
}
}
)
<
`setup {}` can additionally override these defaults in subsequent calls.
==============================================================================
SERVER CONFIGURATIONS *lspconfig-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
configuration directly. This can be useful if there is an outstanding PR that
is in review, or when developing a language server that is unavailable
publicly. This can be done through the `configs` module.
The `configs` module is a singleton where configs are defined. The schema for
validating using `vim.validate` is:
>
configs.SERVER_NAME = {
default_config = {'t'};
on_new_config = {'f', true};
on_attach = {'f', true};
commands = {'t', true};
docs = {'t', true};
}
<
where the structure of the docs table is as follows:
>
docs = {
description = {'s', true};
default_config = {'t', true};
}
<
`commands` is a map of `name:definition` key:value pairs, where `definition`
is a list whose first value is a function implementing the command, and the
rest are either array values which will be formed into flags for the command,
or special keys like `description`. Example:
>
commands = {
TexlabBuild = {
function()
buf_build(0)
end;
"-range";
description = "Build the current buffer";
};
};
<
The `configs.__newindex` metamethod consumes the config definition and returns
an object with a `setup()` method, to be invoked by users:
>
require'lspconfig'.SERVER_NAME.setup{}
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*
The three steps for adding and enabling a new server configuration are:
- load the `lspconfig` module (note that this is a stylistic choice)
>
local lspconfig = require 'lspconfig'
<
- define the configuration
>
local configs = require 'lspconfig/configs'
-- Check if the config is already defined (useful when reloading this file)
if not lspconfig.foo_lsp then
configs.foo_lsp = {
default_config = {
cmd = {'/home/neovim/lua-language-server/run.sh'};
filetypes = {'lua'};
root_dir = function(fname)
return lspconfig.util.find_git_ancestor(fname)
end;
settings = {};
};
}
end
- call `setup()` to enable the FileType autocmd
>
lspconfig.foo_lsp.setup{}
<
==============================================================================
INDEX *lspconfig-index*
The autogenerated documentation for all language servers is accessible in
`server_configurations.md`. Type `gf` on the filename from this document to jump
to the markdown file.
==============================================================================
ROOT DETECTION *lspconfig-root-detection*
*lspconfig-root-dir*
A project's `root_dir` is used by `lspconfig` to determine whether `lspconfig`
should start a new server, or attach a previous one, to the current file.
`lspconfig` automatically launches language servers by defining a filetype
autocommand based on the `filetypes` specified in the default configuration of
each server, optionally overridable by the `filetypes` table passed to
`setup`.
This autocommand triggers a search from the current file position in the
filesystem hierarchy up to the top level directory of your filesystem. The
`root_dir` entry of each configuration is a function that returns true if the
current directory in this traversal matches a given root pattern.
The following utility functions are provided by `lspconfig`. Each function call
below returns a function that takes as its argument the current buffer path.
- `util.root_pattern`: function which takes multiple arguments, each
corresponding to a different root pattern against which the contents of the
current directory are matched using |vim.fin.glob()| while traversing up the
filesystem.
>
root_dir = util.root_pattern('pyproject.toml', 'requirements.txt')
<
- `util.find_git_ancestor`: a function that locates the first parent directory
containing a `.git` directory.
>
root_dir = util.find_git_ancestor
- `util.find_node_modules_ancestor`: a function that locates the first parent
directory containing a `node_modules` directory.
>
root_dir = util.find_node_modules_ancestor
<
- `util.find_package_json_ancestor`: a function that locates the first parent
directory containing a `package.json`.
>
root_dir = util.find_json_ancestor
<
==============================================================================
ADVANCED ROOT DIRECTORY DETECTION *lspconfig-root-composition*
The `root_dir` key in `config` and `setup` can hold any function of the form
>
function custom_root_dir(filename, bufnr)
returns nil | string
>
This allows for rich composition of root directory patterns which is necessary
for some project structures. Example (for Kotlin):
>
local root_files = {
'settings.gradle', -- Gradle (multi-project)
'settings.gradle.kts', -- Gradle (multi-project)
'build.xml', -- Ant
'pom.xml', -- Maven
}
local fallback_root_files = {
'build.gradle', -- Gradle
'build.gradle.kts', -- Gradle
}
root_dir = function(fname)
local primary = util.root_pattern(unpack(root_files))(fname)
local fallback = util.root_pattern(unpack(fallback_root_files))(fname)
return primary or fallback
end
<
Browsing the source of the default configurations is recommended.
==============================================================================
SINGLE FILE SUPPORT *lspconfig-single-file-support*
In order to automatically launch a language server, lspconfig searches up the
directory tree from your current buffer to find a file matching the `root_dir`
pattern defined in each server's configuration. For [pyright](CONFIG.md#pyright)
, this is any directory containing ".git", "setup.py", "setup.cfg",
"pyproject.toml", or "requirements.txt").
Language servers require each project to have a `root` in order to provide
completion and search across symbols that may not be defined in your current
file, and to avoid having to index your entire filesystem on each startup.
many features that require cross-file indexing.
Some servers support not passing a root directory as a proxy for single file
mode under which cross-file features may be degraded. While the built-in
client does not require passing a root directory to a language server,
`lspconfig` requires detecting a project root as it is used internally to
determine whether to attach a given language server to a file or launch a new
instance.
As `lspconfig` configurations are community supported, some community members
have opted to have `lspconfig` detect a file's parent directory as a root.
As a consequence:
* Multi-file "scratch" projects will still allow for cross-file features.
* The server treats `$HOME` the same as any other large directory. The server
will index all files under the project root which can delay startup.
This fallback pattern will be removed in a future version of `lspconfig` in
favor of more explicit handling on a per server basis.
==============================================================================
6. Enabling additional language servers*lspconfig-enabling-additional-language-servers*
COMMANDS *lspconfig-commands*
- `:LspInfo` shows the status of active and configured language servers. Note
that client id refers to the Nvim RPC instance connected to a given
language server.
Enabling most language servers is as easy as installing the language server,
ensuring it is on your PATH, and adding the following to your config:
The following commands support tab-completion for all arguments. All commands
that require a client id can either leverage tab-completion or the info
contained in `:LspInfo`:
- `:LspStart <config_name>` launches the requested (configured) client, but only
if it successfully resolves a root directory. Defaults to all *configured*
servers matching the *current* *buffer's* filetype.
- `:LspStop <client_id>` stops the server with the given client id. Defaults to
stopping all servers active on the current buffer.
- `: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
`on-attach` to selectively apply keybindings after a language servers has
attached to a given buffer.
>
lua << EOF
require'lspconfig'.rust_analyzer.setup{}
EOF
local nvim_lsp = require('lspconfig')
-- Use an on_attach function to only map the following keys
-- after the language server attaches to the current buffer
local on_attach = function(client, bufnr)
local function buf_set_keymap(...) vim.api.nvim_buf_set_keymap(bufnr, ...) end
local function buf_set_option(...) vim.api.nvim_buf_set_option(bufnr, ...) end
-- Enable completion triggered by <c-x><c-o>
buf_set_option('omnifunc', 'v:lua.vim.lsp.omnifunc')
-- Mappings.
local opts = { noremap=true, silent=true }
-- See `:help vim.lsp.*` for documentation on any of the below functions
buf_set_keymap('n', 'gD', '<cmd>lua vim.lsp.buf.declaration()<CR>', opts)
buf_set_keymap('n', 'gd', '<cmd>lua vim.lsp.buf.definition()<CR>', opts)
buf_set_keymap('n', 'K', '<cmd>lua vim.lsp.buf.hover()<CR>', opts)
buf_set_keymap('n', 'gi', '<cmd>lua vim.lsp.buf.implementation()<CR>', opts)
buf_set_keymap('n', '<C-k>', '<cmd>lua vim.lsp.buf.signature_help()<CR>', opts)
buf_set_keymap('n', '<space>wa', '<cmd>lua vim.lsp.buf.add_workspace_folder()<CR>', opts)
buf_set_keymap('n', '<space>wr', '<cmd>lua vim.lsp.buf.remove_workspace_folder()<CR>', opts)
buf_set_keymap('n', '<space>wl', '<cmd>lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))<CR>', opts)
buf_set_keymap('n', '<space>D', '<cmd>lua vim.lsp.buf.type_definition()<CR>', opts)
buf_set_keymap('n', '<space>rn', '<cmd>lua vim.lsp.buf.rename()<CR>', opts)
buf_set_keymap('n', '<space>ca', '<cmd>lua vim.lsp.buf.code_action()<CR>', opts)
buf_set_keymap('n', 'gr', '<cmd>lua vim.lsp.buf.references()<CR>', opts)
buf_set_keymap('n', '<space>e', '<cmd>lua vim.lsp.diagnostic.show_line_diagnostics()<CR>', opts)
buf_set_keymap('n', '[d', '<cmd>lua vim.lsp.diagnostic.goto_prev()<CR>', opts)
buf_set_keymap('n', ']d', '<cmd>lua vim.lsp.diagnostic.goto_next()<CR>', opts)
buf_set_keymap('n', '<space>q', '<cmd>lua vim.lsp.diagnostic.set_loclist()<CR>', opts)
buf_set_keymap('n', '<space>f', '<cmd>lua vim.lsp.buf.formatting()<CR>', opts)
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 ipairs(servers) do
nvim_lsp[lsp].setup {
on_attach = on_attach,
flags = {
debounce_text_changes = 150,
}
}
end
<
Note: these keymappings are meant for illustration and override some
infrequently used default mappings.
For a full list of servers, see [CONFIG.md](CONFIG.md). This document contains
installation instructions and additional, optional customization suggestions
for each language server. For some servers that are not on your system path
(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.
==============================================================================
7. Keybindings *lspconfig-keybindings*
COMPLETION SUPPORT *lspconfig-completion*
Manually triggered completion can be provided by Nvim's built-in omnifunc.
See `:help omnifunc` for more details.
nvim-lspconfig does not map keybindings or enable completion by default.
Manual, triggered completion can be provided by neovim's built-in omnifunc. For
autocompletion, a general purpose [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion)
is required. 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 after the language server has
started (attached to the current buffer)**.
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
>
lua << EOF
local nvim_lsp = require('lspconfig')
-- Use an on_attach function to only map the following keys
-- after the language server attaches to the current buffer
local on_attach = function(client, bufnr)
local function buf_set_keymap(...) vim.api.nvim_buf_set_keymap(bufnr, ...) end
local function buf_set_option(...) vim.api.nvim_buf_set_option(bufnr, ...) end
-- Enable completion triggered by <c-x><c-o>
buf_set_option('omnifunc', 'v:lua.vim.lsp.omnifunc')
-- Mappings.
local opts = { noremap=true, silent=true }
-- See `:help vim.lsp.*` for documentation on any of the below functions
buf_set_keymap('n', 'gD', '<cmd>lua vim.lsp.buf.declaration()<CR>', opts)
buf_set_keymap('n', 'gd', '<cmd>lua vim.lsp.buf.definition()<CR>', opts)
buf_set_keymap('n', 'K', '<cmd>lua vim.lsp.buf.hover()<CR>', opts)
buf_set_keymap('n', 'gi', '<cmd>lua vim.lsp.buf.implementation()<CR>', opts)
buf_set_keymap('n', '<C-k>', '<cmd>lua vim.lsp.buf.signature_help()<CR>', opts)
buf_set_keymap('n', '<space>wa', '<cmd>lua vim.lsp.buf.add_workspace_folder()<CR>', opts)
buf_set_keymap('n', '<space>wr', '<cmd>lua vim.lsp.buf.remove_workspace_folder()<CR>', opts)
buf_set_keymap('n', '<space>wl', '<cmd>lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))<CR>', opts)
buf_set_keymap('n', '<space>D', '<cmd>lua vim.lsp.buf.type_definition()<CR>', opts)
buf_set_keymap('n', '<space>rn', '<cmd>lua vim.lsp.buf.rename()<CR>', opts)
buf_set_keymap('n', '<space>ca', '<cmd>lua vim.lsp.buf.code_action()<CR>', opts)
buf_set_keymap('n', 'gr', '<cmd>lua vim.lsp.buf.references()<CR>', opts)
buf_set_keymap('n', '<space>e', '<cmd>lua vim.lsp.diagnostic.show_line_diagnostics()<CR>', opts)
buf_set_keymap('n', '[d', '<cmd>lua vim.lsp.diagnostic.goto_prev()<CR>', opts)
buf_set_keymap('n', ']d', '<cmd>lua vim.lsp.diagnostic.goto_next()<CR>', opts)
buf_set_keymap('n', '<space>q', '<cmd>lua vim.lsp.diagnostic.set_loclist()<CR>', opts)
buf_set_keymap('n', '<space>f', '<cmd>lua vim.lsp.buf.formatting()<CR>', opts)
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 ipairs(servers) do
nvim_lsp[lsp].setup {
on_attach = on_attach,
flags = {
debounce_text_changes = 150,
}
}
end
EOF
<
The `on_attach` hook is used to only activate the bindings after the language
server attaches to the current buffer.
==============================================================================
8. Debugging *lspconfig-debugging*
DEBUGGING *lspconfig-debugging*
While using language servers should be easy, debugging issues can be
challenging. First, it is important to identify the source of the issue, which
is typically (in rough order):
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).
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, ensure it is on your path.
2. Not triggering root detection. The language server 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 [CONFIG.md](CONFIG.md) or the source for the list of root directories.
3. Misconfiguration. You must pass `on_attach` and `capabilities` for **each** `setup {}` if you want these to take effect. You must also **not call `setup {}` twice for the same server**. The second call to `setup {}` will overwrite the first.
:LspInfo provides a handy overview of your active and configured language
servers. Note, that it will not report any configuration changes applied in
- the language server itself
- a plugin
- overrides in a user configuration
- the built-in client in Nvim core
- `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 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.
- 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.
All bugs Nvim's built-in client should be reported to the Nvim core issue
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:
- The language server is not installed or is otherwise not executable.
`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
|lspconfig-root-directory| for more details. Most of the time,
initializing a git repo will suffice.
- Misconfiguration. Often users will override `cmd`, `on_init`, or
`handlers`. Ensure that you debug by using a stock configuration to ensure
your customizations are not introducing issues.
|LspInfo| provides an overview of your active and configured language servers
which can be useful for debugging.
Note that it will not report any configuration changes applied in
`on_new_config`.
Before reporting a bug, check your logs and the output of `:LspInfo`. Add the
following to your init.vim to enable logging:
==============================================================================
LOGGING *lspconfig-logging*
When debugging language servers, it is helpful to enable additional logging in
the built-in client, specifically considering the RPC logs. Example:
>
lua << EOF
vim.lsp.set_log_level("debug")
EOF
vim.lsp.set_log_level 'trace'
if vim.fn.has 'nvim-0.5.1' == 1 then
require('vim.lsp.log').set_format_func(vim.inspect)
end
<
Attempt to run the language server, and open the log with:
>
:lua vim.cmd('e'..vim.lsp.get_log_path())
<
Note that `ERROR` messages containing `stderr` only indicate that the log was
sent to `stderr`. Many servers counter-intuitively send harmless messages
via stderr.
Most of the time, the reason for failure is present in the logs.
==============================================================================
9. Built-in commands *lspconfig-built-in-commands*
SCOPE *lspconfig-scope*
`lspconfig` is a community effort to create default configurations that fit
within the scope of an official plugin for Nvim. All features that are not
strictly providing default configurations for language servers will be removed
from `lspconfig` in time. The power of the Neovim LSP ecosystem is in the
composability and flexibility of integrating multiple plugins which maximizes
user choice and freedom.
`lspconfig` also opts to adhere strictly to the LSP specification, with some
small allowances when small modifications to a server configuration are
necessary to enable features critical to its usability. For more featureful
options, the `lspconfig` wiki lists community created plugins that build upon
the built-in client to provide functionality tailored to specific language
servers.
* `: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.
==============================================================================
10. The wiki *lspconfig-the-wiki*
Please see the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for
additional topics, including:
* [Installing language servers automatically](https://github.com/neovim/nvim-lspconfig/wiki/Installing-language-servers-automatically)
* [Snippets support](https://github.com/neovim/nvim-lspconfig/wiki/Snippets)
* [Project local settings](https://github.com/neovim/nvim-lspconfig/wiki/Project-local-settings)
* [Recommended plugins for enhanced language server features](https://github.com/neovim/nvim-lspconfig/wiki/Language-specific-plugins)
==============================================================================
11. Windows *lspconfig-windows*
In order for neovim to launch certain executables on Windows, it must append
`.cmd` to the command name. To work around this, manually append `.cmd` to the
entry `cmd` in a given plugin's setup{} call.
==============================================================================
12. Contributions *lspconfig-contributions*
If you are missing a language server on the list in [CONFIG.md](CONFIG.md) ,
contributing a new configuration for it would be appreciated. You can follow
these steps:
1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
2. Choose a language from [the coc.nvim wiki](https://github.com/neoclide/coc.nvim/wiki/Language-servers) or
[emacs-lsp](https://github.com/emacs-lsp/lsp-mode#supported-languages).
3. Create a new file at `lua/lspconfig/SERVER_NAME.lua`.
- Copy an [existing config](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/)
to get started. Most configs are simple. For an extensive example see
[texlab.lua](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/texlab.lua).
4. Ask questions on our [Discourse](https://neovim.discourse.group/c/7-category/7) or in the [Neovim Gitter](https://gitter.im/neovim/neovim).
vim:tw=78:ts=8:ft=help:norl:
vim:tw=78:ts=8:ft=help:norl:

7839
doc/server_configurations.md Normal file
View File

File diff suppressed because it is too large Load Diff

2
scripts/docgen.lua
View File

@ -272,7 +272,7 @@ local function generate_readme(template_file, params)
local input_template = readfile(template_file)
local readme_data = template(input_template, params)
local writer = io.open('CONFIG.md', 'w')
local writer = io.open('doc/server_configurations.md', 'w')
writer:write(readme_data)
writer:close()
end

28
scripts/vimdocgen.lua
View File

@ -1,28 +0,0 @@
local docgen = require 'babelfish'
local docs = {}
docs.generate = function()
local metadata = {
input_file = './README.md',
output_file = './doc/lspconfig.txt',
project_name = 'lspconfig',
header_aliases = {
['Example: using the defaults'] = { 'Defaults', 'defaults' },
['Example: override some defaults'] = { 'Overriding server defaults', 'override-server-defaults' },
['Example: custom config'] = { 'Custom config', 'custom-config' },
['Example: override default config for all servers'] = { 'Overriding all defaults', 'override-all-defaults' },
['Individual server settings and initialization options'] = {
'Per-server documentation',
'server-documentation',
},
['Keybindings and completion'] = { 'Keybindings', 'keybindings' },
['Manually starting (or restarting) language servers'] = { 'Manual control', 'manual-control' },
},
}
docgen.generate_readme(metadata)
end
docs.generate()
return docs