Skip to content

Commit

Permalink
Add docs for Ruff language server
Browse files Browse the repository at this point in the history
  • Loading branch information
@dhruvmanila
dhruvmanila committed Jul 17, 2024
1 parent 9a817a2 commit 9163ad8
Show file tree
Hide file tree
Showing 14 changed files with 1,131 additions and 461 deletions.
84 changes: 1 addition & 83 deletions crates/ruff_server/docs/MIGRATION.md
View file
Original file line number Diff line number Diff line change
@@ -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/server/#migratin-from-ruff-lsp>.
100 changes: 1 addition & 99 deletions crates/ruff_server/docs/setup/HELIX.md
View file
Original file line number Diff line number Diff line change
@@ -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.

![A screenshot showing an open Python file in Helix with highlighted diagnostics and a code action dropdown menu open](assets/SuccessfulHelixSetup.png)
*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/server/#helix>.
24 changes: 1 addition & 23 deletions crates/ruff_server/docs/setup/KATE.md
View file
Original file line number Diff line number Diff line change
@@ -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/server/#kate>.
93 changes: 1 addition & 92 deletions crates/ruff_server/docs/setup/NEOVIM.md
View file
Original file line number Diff line number Diff line change
@@ -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/server/#neovim>.
40 changes: 1 addition & 39 deletions crates/ruff_server/docs/setup/VIM.md
View file
Original file line number Diff line number Diff line change
@@ -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/server/#vim>.
Binary file removed crates/ruff_server/docs/setup/assets/SuccessfulHelixSetup.png
View file
Binary file not shown.
10 changes: 5 additions & 5 deletions docs/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
contributing.md
index.md
rules.md
rules/
settings.md
/contributing.md
/index.md
/rules.md
/rules/
/settings.md
Loading

0 comments on commit 9163ad8

Please sign in to comment.