Skip to content

Commit

Permalink
Add docs for Ruff language server (#12344)
Browse files Browse the repository at this point in the history 
## 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`
  • Loading branch information
@dhruvmanila
dhruvmanila authored Jul 18, 2024
1 parent 2e77b77 commit 648cca1
Show file tree
Hide file tree
Showing 15 changed files with 1,254 additions and 731 deletions.
72 changes: 7 additions & 65 deletions crates/ruff_server/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
## The Ruff Language Server

Welcome!
# The Ruff Language Server

`ruff server` is a language server that powers Ruff's editor integrations.

Expand All @@ -9,68 +7,12 @@ and call into Ruff's linter and formatter crates to construct real-time diagnost
sent back to the client. It also tracks configuration files in your editor's workspace, and will refresh its in-memory
configuration whenever those files are modified.

### Setup

We have specific setup instructions depending on your editor. If you don't see your editor on this list and would like a
setup guide, please open an issue.

If you're transferring your configuration from [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp), regardless of
editor, there are several settings which have changed or are no longer available. See the [migration guide](docs/MIGRATION.md) for
more.

#### VS Code

Install the Ruff extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff).

As this server is still in Beta, you will need to enable the "Native Server" extension setting, either in the settings
UI:

![A screenshot showing an enabled "Native Server" extension setting in the VS Code settings view](assets/nativeServer.png)

Or in your `settings.json`:

```json
{
"ruff.nativeServer": true
}
```

From there, you can configure Ruff to format Python code on-save with:

```json
{
"[python]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
```

For more, see [_Configuring VS Code_](https://github.com/astral-sh/ruff-vscode?tab=readme-ov-file#configuring-vs-code)
in the Ruff extension documentation.

By default, the extension will run against the `ruff` binary that it discovers in your environment. If you don't have
`ruff` installed, the extension will fall back to a bundled version of the binary.

#### Neovim

See the [Neovim setup guide](docs/setup/NEOVIM.md).

#### Helix

See the [Helix setup guide](docs/setup//HELIX.md).

#### Vim

See the [Vim setup guide](docs/setup/VIM.md).

#### Kate

See the [Kate setup guide](docs/setup/KATE.md).
Refer to the [documentation](https://docs.astral.sh/ruff/editors/) for more information on
how to set up the language server with your editor and configure it to your liking.

### Contributing
## Contributing

If you're interested in contributing to `ruff server` - well, first of all, thank you! Second of all, you might find the
[**contribution guide**](CONTRIBUTING.md) to be a useful resource.
Contributions are welcome and highly appreciated. To get started, check out the
[**contributing guidelines**](https://docs.astral.sh/ruff/contributing/).

Finally, don't hesitate to reach out on [**Discord**](https://discord.com/invite/astral-sh) if you have questions.
You can also join us on [**Discord**](https://discord.com/invite/astral-sh).
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/editors/migration>.
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/editors/setup/#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/editors/setup/#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/editors/setup/#neovim>.
Loading

0 comments on commit 648cca1

Please sign in to comment.