diff --git a/crates/ruff_server/README.md b/crates/ruff_server/README.md index ba28bbb45b..d130f57b71 100644 --- a/crates/ruff_server/README.md +++ b/crates/ruff_server/README.md @@ -1,31 +1,56 @@ ## The Ruff Language Server -Welcome! `ruff server` is a language server that powers editor integrations with Ruff. The job of the language server is to -listen for requests from the client, (in this case, the code editor of your choice) and call into Ruff's linter and formatter -crates to create real-time diagnostics or formatted code, which is then 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. +Welcome! + +`ruff server` is a language server that powers Ruff's editor integrations. + +The job of the language server is to listen for requests from the client (in this case, the code editor of your choice) +and call into Ruff's linter and formatter crates to construct real-time diagnostics or formatted code, which is then +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. +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. -#### Visual Studio Code +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. -Install the [Ruff extension from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff). +#### VS Code -As this server is still in beta, you will need to enable the `Native Server` extension setting: +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) -You can also set it in your user / workspace JSON settings as follows: +Or in your `settings.json`: ```json { - "ruff.nativeServer": true + "ruff.nativeServer": true } ``` -The language server used by the extension will be, by default, the one in your actively-installed `ruff` binary. If you don't have `ruff` installed and haven't provided a path to the extension, it comes with a bundled `ruff` version that it will use instead. +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 @@ -35,8 +60,9 @@ See the [Neovim setup guide](docs/setup/NEOVIM.md). See the [Helix setup guide](docs/setup//HELIX.md). -If you are transferring your configuration from `ruff-lsp`, regardless of editor, there are several settings which have changed or are no longer available which you should be aware of. See the [migration guide](docs/MIGRATION.md) for more details. - ### 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. Finally, don't hesitate to reach out on our [**Discord**](https://discord.com/invite/astral-sh) if you have questions. +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. + +Finally, don't hesitate to reach out on [**Discord**](https://discord.com/invite/astral-sh) if you have questions. diff --git a/crates/ruff_server/docs/MIGRATION.md b/crates/ruff_server/docs/MIGRATION.md index f0d420c2b2..9b42ca0ee6 100644 --- a/crates/ruff_server/docs/MIGRATION.md +++ b/crates/ruff_server/docs/MIGRATION.md @@ -1,12 +1,13 @@ ## Migrating From `ruff-lsp` -`ruff server`'s configuration is significantly different from `ruff-lsp`, and as such you may need to update your existing configuration. +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 settings have documentation that will tell you whether `ruff server` supports a given setting. -> This migration guide may be more useful for the editors that do not have explicitly documented settings for the language server, -> such as Helix or Neovim. +> 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 @@ -20,14 +21,15 @@ Several `ruff-lsp` settings are not supported by `ruff server`. These are, as fo - `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 set the ruff binary -used to run `ruff server`. But the server itself will no longer accept these as settings. +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`: This is 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. +- `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. @@ -40,8 +42,9 @@ used to run `ruff server`. But the server itself will no longer accept these as - `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 have been passing in `--select=` -to `lint.args`, you can migrate to the new server by using `lint.select` with a value of `[""]`. +Several of these new settings are replacements for the now-unsupported `format.args` and `lint.args`. For example, if +you've been passing `--select=` to `lint.args`, you can migrate to the new server by using `lint.select` with a +value of `[""]`. ### Examples @@ -53,7 +56,7 @@ Let's say you have these settings in VS Code: } ``` -These can be migrated to the new language server like so: +After enabling the native server, you can migrate your settings like so: ```json {