mirror of
https://github.com/astral-sh/ruff.git
synced 2025-08-04 10:48:32 +00:00
Add docs for Ruff language server (#12344)
## Summary This PR adds documentation for the Ruff language server. It mainly does the following: 1. Combines various READMEs containing instructions for different editor setup in their respective section on the online docs 2. Provide an enumerated list of server settings. Additionally, it also provides a section for VS Code specific options. 3. Adds a "Features" section which enumerates all the current capabilities of the native server For (2), the settings documentation is done manually but a future improvement (easier after `ruff-lsp` is deprecated) is to move the docs in to Rust struct and generate the documentation from the code itself. And, the VS Code extension specific options can be generated by diffing against the `package.json` in `ruff-vscode` repository. ### Structure 1. Setup: This section contains the configuration for setting up the language server for different editors 2. Features: This section contains a list of capabilities provided by the server along with short GIF to showcase it 3. Settings: This section contains an enumerated list of settings in a similar format to the one for the linter / formatter 4. Migrating from `ruff-lsp` > [!NOTE] > > The settings page is manually written but could possibly be auto-generated via a macro similar to `OptionsMetadata` on the `ClientSettings` struct resolves: #11217 ## Test Plan Generate and open the documentation locally using: 1. `python scripts/generate_mkdocs.py` 2. `mkdocs serve -f mkdocs.insiders.yml`
This commit is contained in:
Dhruv Manilawala
GitHub
parent
2e77b775b0
commit
648cca199b
15 changed files with 1254 additions and 731 deletions
|
|
@ -1,85 +1,3 @@
|
|||
## Migrating From `ruff-lsp`
|
||||
|
||||
While `ruff server` supports the same feature set as [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp), migrating to
|
||||
`ruff server` may require changes to your Ruff or language server configuration.
|
||||
|
||||
> \[!NOTE\]
|
||||
>
|
||||
> The [VS Code extension](https://github.com/astral-sh/ruff-vscode) settings include documentation to indicate which
|
||||
> settings are supported by `ruff server`. As such, this migration guide is primarily targeted at editors that lack
|
||||
> explicit documentation for `ruff server` settings, such as Helix or Neovim.
|
||||
|
||||
### Unsupported Settings
|
||||
|
||||
Several `ruff-lsp` settings are not supported by `ruff server`. These are, as follows:
|
||||
|
||||
- `format.args`
|
||||
- `ignoreStandardLibrary`
|
||||
- `interpreter`
|
||||
- `lint.args`
|
||||
- `lint.run`
|
||||
- `logLevel`
|
||||
- `path`
|
||||
|
||||
Note that some of these settings, like `interpreter` and `path`, are still accepted by the VS Code extension. `path`,
|
||||
in particular, can be used to specify a dedicated binary to use when initializing `ruff server`. But the language server
|
||||
itself will no longer accept such settings.
|
||||
|
||||
### New Settings
|
||||
|
||||
`ruff server` introduces several new settings that `ruff-lsp` does not have. These are, as follows:
|
||||
|
||||
- `configuration`: A path to a `ruff.toml` or `pyproject.toml` file to use for configuration. By default, Ruff will discover configuration for each project from the filesystem, mirroring the behavior of the Ruff CLI.
|
||||
- `configurationPreference`: Used to specify how you want to resolve server settings with local file configuration. The following values are available:
|
||||
- `"editorFirst"`: The default strategy - configuration set in the server settings takes priority over configuration set in `.toml` files.
|
||||
- `"filesystemFirst"`: An alternative strategy - configuration set in `.toml` files takes priority over configuration set in the server settings.
|
||||
- `"editorOnly"`: An alternative strategy - configuration set in `.toml` files is ignored entirely.
|
||||
- `exclude`: Paths for the linter and formatter to ignore. See [the documentation](https://docs.astral.sh/ruff/settings/#exclude) for more details.
|
||||
- `format.preview`: Enables [preview mode](https://docs.astral.sh/ruff/settings/#format_preview) for the formatter; enables unstable formatting.
|
||||
- `lineLength`: The [line length](https://docs.astral.sh/ruff/settings/#line-length) used by the formatter and linter.
|
||||
- `lint.select`: The rule codes to enable. Use `ALL` to enable all rules. See [the documentation](https://docs.astral.sh/ruff/settings/#lint_select) for more details.
|
||||
- `lint.extendSelect`: Enables additional rule codes on top of existing configuration, instead of overriding it. Use `ALL` to enable all rules.
|
||||
- `lint.ignore`: Sets rule codes to disable. See [the documentation](https://docs.astral.sh/ruff/settings/#lint_ignore) for more details.
|
||||
- `lint.preview`: Enables [preview mode](https://docs.astral.sh/ruff/settings/#lint_preview) for the linter; enables unstable rules and fixes.
|
||||
|
||||
Several of these new settings are replacements for the now-unsupported `format.args` and `lint.args`. For example, if
|
||||
you've been passing `--select=<RULES>` to `lint.args`, you can migrate to the new server by using `lint.select` with a
|
||||
value of `["<RULES>"]`.
|
||||
|
||||
### Examples
|
||||
|
||||
Let's say you have these settings in VS Code:
|
||||
|
||||
```json
|
||||
{
|
||||
"ruff.lint.args": "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml"
|
||||
}
|
||||
```
|
||||
|
||||
After enabling the native server, you can migrate your settings like so:
|
||||
|
||||
```json
|
||||
{
|
||||
"ruff.configuration": "~/.config/custom_ruff_config.toml",
|
||||
"ruff.lineLength": 80,
|
||||
"ruff.lint.select": ["E", "F"]
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, let's say you have these settings in Helix:
|
||||
|
||||
```toml
|
||||
[language-server.ruff.config.lint]
|
||||
args = "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml"
|
||||
```
|
||||
|
||||
These can be migrated like so:
|
||||
|
||||
```toml
|
||||
[language-server.ruff.config]
|
||||
configuration = "~/.config/custom_ruff_config.toml"
|
||||
lineLength = 80
|
||||
|
||||
[language-server.ruff.config.lint]
|
||||
select = ["E", "F"]
|
||||
```
|
||||
This document has been moved to <https://docs.astral.sh/ruff/editors/migration>.
|
||||
|
|
|
|||
|
|
@ -1,101 +1,3 @@
|
|||
## Helix Setup Guide for `ruff server`
|
||||
|
||||
First, open the language configuration file for Helix. On Linux and macOS, this will be at `~/.config/helix/languages.toml`,
|
||||
and on Windows this will be at `%AppData%\helix\languages.toml`.
|
||||
|
||||
Add the language server by adding:
|
||||
|
||||
```toml
|
||||
[language-server.ruff]
|
||||
command = "ruff"
|
||||
args = ["server", "--preview"]
|
||||
```
|
||||
|
||||
Then, you'll register the language server as the one to use with Python.
|
||||
If you don't already have a language server registered to use with Python, add this to `languages.toml`:
|
||||
|
||||
```toml
|
||||
[[language]]
|
||||
name = "python"
|
||||
language-servers = ["ruff"]
|
||||
```
|
||||
|
||||
Otherwise, if you already have `language-servers` defined, you can simply add `"ruff"` to the list. For example,
|
||||
if you already have `pylsp` as a language server, you can modify the language entry as follows:
|
||||
|
||||
```toml
|
||||
[[language]]
|
||||
name = "python"
|
||||
language-servers = ["ruff", "pylsp"]
|
||||
```
|
||||
|
||||
> \[!NOTE\]
|
||||
> Multiple language servers for a single language are only supported in Helix version [`23.10`](https://github.com/helix-editor/helix/blob/master/CHANGELOG.md#2310-2023-10-24) and later.
|
||||
|
||||
Once you've set up the server, you should see diagnostics in your Python files. Code actions and other LSP features should also be available.
|
||||
|
||||
|
||||
*This screenshot is using `select=["ALL]"` for demonstration purposes.*
|
||||
|
||||
If you want to, as an example, turn on auto-formatting, add `auto-format = true`:
|
||||
|
||||
```toml
|
||||
[[language]]
|
||||
name = "python"
|
||||
language-servers = ["ruff", "pylsp"]
|
||||
auto-format = true
|
||||
```
|
||||
|
||||
See the [Helix documentation](https://docs.helix-editor.com/languages.html) for more settings you can use here.
|
||||
|
||||
You can pass settings into `ruff server` using `[language-server.ruff.config.settings]`. For example:
|
||||
|
||||
```toml
|
||||
[language-server.ruff.config.settings]
|
||||
lineLength = 80
|
||||
[language-server.ruff.config.settings.lint]
|
||||
select = ["E4", "E7"]
|
||||
preview = false
|
||||
[language-server.ruff.config.settings.format]
|
||||
preview = true
|
||||
```
|
||||
|
||||
By default, Ruff does not log anything to Helix. To enable logging, set the `RUFF_TRACE` environment variable
|
||||
to either `messages` or `verbose`.
|
||||
|
||||
```toml
|
||||
[language-server.ruff]
|
||||
command = "ruff"
|
||||
args = ["server", "--preview"]
|
||||
environment = { "RUFF_TRACE" = "messages" }
|
||||
```
|
||||
|
||||
> \[!NOTE\]
|
||||
> `RUFF_TRACE=verbose` does not enable Helix's verbose mode by itself. You'll need to run Helix with `-v` for verbose logging.
|
||||
|
||||
To change the log level for Ruff (which is `info` by default), use the `logLevel` setting:
|
||||
|
||||
```toml
|
||||
[language-server.ruff]
|
||||
command = "ruff"
|
||||
args = ["server", "--preview"]
|
||||
environment = { "RUFF_TRACE" = "messages" }
|
||||
|
||||
[language-server.ruff.config.settings]
|
||||
logLevel = "debug"
|
||||
```
|
||||
|
||||
You can also divert Ruff's logs to a separate file with the `logFile` setting:
|
||||
|
||||
```toml
|
||||
[language-server.ruff]
|
||||
command = "ruff"
|
||||
args = ["server", "--preview"]
|
||||
environment = { "RUFF_TRACE" = "messages" }
|
||||
|
||||
[language-server.ruff.config.settings]
|
||||
logLevel = "debug"
|
||||
logFile = "~/.cache/helix/ruff.log"
|
||||
```
|
||||
|
||||
The `logFile` path supports tildes and environment variables.
|
||||
This document has been moved to <https://docs.astral.sh/ruff/editors/setup/#helix>.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,3 @@
|
|||
## Kate Setup Guide for `ruff server`
|
||||
|
||||
1. Activate the [LSP Client plugin](https://docs.kde.org/stable5/en/kate/kate/plugins.html#kate-application-plugins).
|
||||
1. Setup LSP Client [as desired](https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-lspclient.html).
|
||||
1. Finally, add this to `Settings` -> `Configure Kate` -> `LSP Client` -> `User Server Settings`:
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"python": {
|
||||
"command": ["ruff", "server", "--preview"],
|
||||
"url": "https://github.com/astral-sh/ruff",
|
||||
"highlightingModeRegex": "^Python$",
|
||||
"settings": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [LSP Client documentation](https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-lspclient.html) for more details
|
||||
on how to configure the server from there.
|
||||
|
||||
> \[!IMPORTANT\]
|
||||
>
|
||||
> Kate's LSP Client plugin does not support multiple servers for the same language.
|
||||
This document has been moved to <https://docs.astral.sh/ruff/editors/setup/#kate>.
|
||||
|
|
|
|||
|
|
@ -1,94 +1,3 @@
|
|||
## Neovim Setup Guide for `ruff server`
|
||||
|
||||
### Using `nvim-lspconfig`
|
||||
|
||||
1. Install [`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig).
|
||||
1. Setup `nvim-lspconfig` with the [suggested configuration](https://github.com/neovim/nvim-lspconfig/tree/master#suggested-configuration).
|
||||
1. Finally, add this to your `init.lua`:
|
||||
|
||||
```lua
|
||||
require('lspconfig').ruff.setup {}
|
||||
```
|
||||
|
||||
See [`nvim-lspconfig`'s server configuration guide](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ruff) for more details
|
||||
on how to configure the server from there.
|
||||
|
||||
> \[!IMPORTANT\]
|
||||
>
|
||||
> If you have the older language server (`ruff-lsp`) configured in Neovim, make sure to disable it to prevent any conflicts.
|
||||
|
||||
#### Tips
|
||||
|
||||
If you're using Ruff alongside another LSP (like Pyright), you may want to defer to that LSP for certain capabilities,
|
||||
like `textDocument/hover`:
|
||||
|
||||
```lua
|
||||
local on_attach = function(client, bufnr)
|
||||
if client.name == 'ruff' then
|
||||
-- Disable hover in favor of Pyright
|
||||
client.server_capabilities.hoverProvider = false
|
||||
end
|
||||
end
|
||||
|
||||
require('lspconfig').ruff.setup {
|
||||
on_attach = on_attach,
|
||||
}
|
||||
```
|
||||
|
||||
If you'd like to use Ruff exclusively for linting, formatting, and import organization, you can disable those
|
||||
capabilities for Pyright:
|
||||
|
||||
```lua
|
||||
require('lspconfig').pyright.setup {
|
||||
settings = {
|
||||
pyright = {
|
||||
-- Using Ruff's import organizer
|
||||
disableOrganizeImports = true,
|
||||
},
|
||||
python = {
|
||||
analysis = {
|
||||
-- Ignore all files for analysis to exclusively use Ruff for linting
|
||||
ignore = { '*' },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
By default, Ruff will not show any logs. To enable logging in Neovim, you'll need to set the `RUFF_TRACE` environment variable
|
||||
to either `messages` or `verbose`:
|
||||
|
||||
```lua
|
||||
require('lspconfig').ruff.setup {
|
||||
cmd_env = { RUFF_TRACE = "messages" }
|
||||
}
|
||||
```
|
||||
|
||||
You can set the log level in `settings`:
|
||||
|
||||
```lua
|
||||
require('lspconfig').ruff.setup {
|
||||
cmd_env = { RUFF_TRACE = "messages" },
|
||||
init_options = {
|
||||
settings = {
|
||||
logLevel = "debug",
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It's also possible to divert Ruff's logs to a separate file with the `logFile` setting:
|
||||
|
||||
```lua
|
||||
require('lspconfig').ruff.setup {
|
||||
cmd_env = { RUFF_TRACE = "messages" },
|
||||
init_options = {
|
||||
settings = {
|
||||
logLevel = "debug",
|
||||
logFile = "~/.local/state/nvim/ruff.log"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `logFile` path supports tildes and environment variables.
|
||||
This document has been moved to <https://docs.astral.sh/ruff/editors/setup/#neovim>.
|
||||
|
|
|
|||
|
|
@ -1,41 +1,3 @@
|
|||
## Vim Setup Guide for `ruff server`
|
||||
|
||||
### Using `vim-lsp`
|
||||
|
||||
1. Install [`vim-lsp`](https://github.com/prabirshrestha/vim-lsp).
|
||||
1. Setup `vim-lsp` [as desired](https://github.com/prabirshrestha/vim-lsp?tab=readme-ov-file#registering-servers).
|
||||
1. Finally, add this to your `.vimrc`:
|
||||
|
||||
```vim
|
||||
if executable('ruff')
|
||||
au User lsp_setup call lsp#register_server({
|
||||
\ 'name': 'ruff',
|
||||
\ 'cmd': {server_info->['ruff', 'server', '--preview']},
|
||||
\ 'allowlist': ['python'],
|
||||
\ 'workspace_config': {},
|
||||
\ })
|
||||
endif
|
||||
```
|
||||
|
||||
See the `vim-lsp` [documentation](https://github.com/prabirshrestha/vim-lsp/blob/master/doc/vim-lsp.txt) for more
|
||||
details on how to configure the language server.
|
||||
|
||||
> \[!IMPORTANT\]
|
||||
>
|
||||
> If Ruff's legacy language server (`ruff-lsp`) is configured in Vim, be sure to disable it to prevent any conflicts.
|
||||
|
||||
#### Tips
|
||||
|
||||
If you're using Ruff alongside another LSP (like Pyright), you may want to defer to that LSP for certain capabilities,
|
||||
like `textDocument/hover` by adding the following to the function `s:on_lsp_buffer_enabled()`:
|
||||
|
||||
```vim
|
||||
function! s:on_lsp_buffer_enabled() abort
|
||||
" add your keybindings here (see https://github.com/prabirshrestha/vim-lsp?tab=readme-ov-file#registering-servers)
|
||||
|
||||
let l:capabilities = lsp#get_server_capabilities('ruff')
|
||||
if !empty(l:capabilities)
|
||||
let l:capabilities.hoverProvider = v:false
|
||||
endif
|
||||
endfunction
|
||||
```
|
||||
This document has been moved to <https://docs.astral.sh/ruff/editors/setup/#vim>.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 195 KiB |
Loading…
Add table
Add a link
Reference in a new issue