From 800ff0a6935b7b8df091318c6577e45f2373f9ed Mon Sep 17 00:00:00 2001 From: Jane Lewis Date: Wed, 26 Jun 2024 15:28:43 -0700 Subject: [PATCH 1/5] Update Integrations page to cover `ruff server` --- docs/integrations.md | 442 +++++++++++++++++++++++-------------------- 1 file changed, 234 insertions(+), 208 deletions(-) diff --git a/docs/integrations.md b/docs/integrations.md index 10f97dfc2b4d9..98532a01f9b16 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -1,272 +1,241 @@ -# Integrations +# Editor Integrations + +## Ruff Language Server (`ruff server`) + +The Ruff language server, also known as `ruff server`, is what powers the diagnostic and formatting capabilities of Ruff's VS Code extension and other editors. It is a single, common backend for editor integrations built directly into Ruff, and a direct replacement for `ruff-lsp`, our previous language server. You can read more about `ruff server` in the [`v0.4.5` blog post](https://astral.sh/blog/ruff-v0.4.5). + +`ruff server` uses the LSP (Language Server Protocol), and as such works with any editor that supports this protocol. VS Code, Neovim, Helix, and Kate all have official, documented support for `ruff server`. Other editors may support the older `ruff-lsp` server - see the [Setup](https://github.com/astral-sh/ruff-lsp#setup) guide in `ruff-lsp` for more details. ## VS Code (Official) -Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff), -which supports fix actions, import sorting, and more. +Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff), which supports fix actions, import sorting, and more. -![Ruff VS Code extension](https://user-images.githubusercontent.com/1309177/205175763-cf34871d-5c05-4abf-9916-440afc82dbf8.gif) +By default, the extension will attempt to use the `ruff` executable installed on your local system, and will use a bundled executable if that's not available. If `ruff` is `v0.4.5` or later, the extension will automatically use `ruff server` - otherwise, it will use `ruff-lsp`. To configure this behavior, refer to the `languageServer` setting (add link here). -## pre-commit +To learn more about configuring the extension, and the settings available for the extension, refer to [Configuring Ruff](https://github.com/astral-sh/ruff-vscode/?tab=readme-ov-file#configuring-ruff) in the `ruff-vscode` documentation. -Ruff can be used as a [pre-commit](https://pre-commit.com) hook via [`ruff-pre-commit`](https://github.com/astral-sh/ruff-pre-commit): +## Vim & Neovim (Official) -```yaml -- repo: https://github.com/astral-sh/ruff-pre-commit - # Ruff version. - rev: v0.4.10 - hooks: - # Run the linter. - - id: ruff - # Run the formatter. - - id: ruff-format -``` +### Using `nvim-lspconfig` -To enable lint fixes, add the `--fix` argument to the lint hook: +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`: -```yaml -- repo: https://github.com/astral-sh/ruff-pre-commit - # Ruff version. - rev: v0.4.10 - hooks: - # Run the linter. - - id: ruff - args: [ --fix ] - # Run the formatter. - - id: ruff-format +```lua +require('lspconfig').ruff.setup {} ``` -To run the hooks over Jupyter Notebooks too, add `jupyter` to the list of allowed filetypes: +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. -```yaml -- repo: https://github.com/astral-sh/ruff-pre-commit - # Ruff version. - rev: v0.4.10 - hooks: - # Run the linter. - - id: ruff - types_or: [ python, pyi, jupyter ] - args: [ --fix ] - # Run the formatter. - - id: ruff-format - types_or: [ python, pyi, jupyter ] -``` +> \[!IMPORTANT\] +> +> If you have the older language server (`ruff-lsp`) configured in Neovim, make sure to disable it to prevent any conflicts. -When running with `--fix`, Ruff's lint hook should be placed _before_ Ruff's formatter hook, and -_before_ Black, isort, and other formatting tools, as Ruff's fix behavior can output code changes -that require reformatting. +#### Tips -When running without `--fix`, Ruff's formatter hook can be placed before or after Ruff's lint hook. +If you're using Ruff alongside another LSP (like Pyright), you may want to defer to that LSP for certain capabilities, +like `textDocument/hover`: -(As long as your Ruff configuration avoids any [linter-formatter incompatibilities](formatter.md#conflicting-lint-rules), -`ruff format` should never introduce new lint errors, so it's safe to run Ruff's format hook _after_ -`ruff check --fix`.) +```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, +} +``` -## Language Server Protocol (Official) +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 = { '*' }, + }, + }, + }, +} +``` -Ruff supports the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) -via the [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) Python package, available on -[PyPI](https://pypi.org/project/ruff-lsp/). +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`: -[`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) enables Ruff to be used with any editor that -supports the Language Server Protocol, including [Neovim](https://github.com/astral-sh/ruff-lsp#example-neovim), -[Sublime Text](https://github.com/astral-sh/ruff-lsp#example-sublime-text), Emacs, and more. +```lua +require('lspconfig').ruff.setup { + cmd_env = { RUFF_TRACE = "messages" } +} +``` -For example, to use `ruff-lsp` with Neovim, install `ruff-lsp` from PyPI along with -[`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig). Then, set up the Neovim LSP client -using the [suggested configuration](https://github.com/neovim/nvim-lspconfig/tree/master#configuration) -(`:h lspconfig-keybindings`). Finally, configure `ruff-lsp` in your `init.lua`: +You can set the log level in `settings`: ```lua --- Configure `ruff-lsp`. --- See: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ruff_lsp --- For the default config, along with instructions on how to customize the settings -require('lspconfig').ruff_lsp.setup { +require('lspconfig').ruff.setup { + cmd_env = { RUFF_TRACE = "messages" }, init_options = { settings = { - -- Any extra CLI arguments for `ruff` go here. - args = {}, + logLevel = "debug", } } } ``` -Upon successful installation, you should see Ruff's diagnostics surfaced directly in your editor: +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" + } + } +} +``` -![Code Actions available in Neovim](https://user-images.githubusercontent.com/1309177/208278707-25fa37e4-079d-4597-ad35-b95dba066960.png) +The `logFile` path supports tildes and environment variables. -To use `ruff-lsp` with other editors, including Sublime Text and Helix, see the [`ruff-lsp` documentation](https://github.com/astral-sh/ruff-lsp#installation-and-usage). +## Helix (Official) -## Language Server Protocol (Unofficial) +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`. -Ruff is also available as the [`python-lsp-ruff`](https://github.com/python-lsp/python-lsp-ruff) -plugin for [`python-lsp-server`](https://github.com/python-lsp/python-lsp-server), both of which are -installable from PyPI: +Add the language server by adding: -```shell -pip install python-lsp-server python-lsp-ruff +```toml +[language-server.ruff] +command = "ruff" +args = ["server", "--preview"] ``` -The LSP server can then be used with any editor that supports the Language Server Protocol. +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`: -For example, to use `python-lsp-ruff` with Neovim, add something like the following to your -`init.lua`: +```toml +[[language]] +name = "python" +language-servers = ["ruff"] +``` -```lua -require'lspconfig'.pylsp.setup { - settings = { - pylsp = { - plugins = { - ruff = { - enabled = true - }, - pycodestyle = { - enabled = false - }, - pyflakes = { - enabled = false - }, - mccabe = { - enabled = false - } - } - } - }, -} +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"] ``` -## Vim & Neovim +> \[!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. -Ruff can be integrated into any editor that supports the Language Server Protocol via [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) -(see: [Language Server Protocol](#language-server-protocol-official)), including Vim and Neovim. +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. -It's recommended that you use [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp), the -officially supported LSP server for Ruff. To use `ruff-lsp` with Neovim, install `ruff-lsp` from -PyPI along with [`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig). Then, add something -like the following to your `init.lua`: +![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.* -```lua --- See: https://github.com/neovim/nvim-lspconfig/tree/54eb2a070a4f389b1be0f98070f81d23e2b1a715#suggested-configuration -local opts = { noremap=true, silent=true } -vim.keymap.set('n', 'e', vim.diagnostic.open_float, opts) -vim.keymap.set('n', '[d', vim.diagnostic.goto_prev, opts) -vim.keymap.set('n', ']d', vim.diagnostic.goto_next, opts) -vim.keymap.set('n', 'q', vim.diagnostic.setloclist, opts) - --- 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) - -- Enable completion triggered by - vim.api.nvim_buf_set_option(bufnr, 'omnifunc', 'v:lua.vim.lsp.omnifunc') - - -- Mappings. - -- See `:help vim.lsp.*` for documentation on any of the below functions - local bufopts = { noremap=true, silent=true, buffer=bufnr } - vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, bufopts) - vim.keymap.set('n', 'gd', vim.lsp.buf.definition, bufopts) - vim.keymap.set('n', 'K', vim.lsp.buf.hover, bufopts) - vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, bufopts) - vim.keymap.set('n', '', vim.lsp.buf.signature_help, bufopts) - vim.keymap.set('n', 'wa', vim.lsp.buf.add_workspace_folder, bufopts) - vim.keymap.set('n', 'wr', vim.lsp.buf.remove_workspace_folder, bufopts) - vim.keymap.set('n', 'wl', function() - print(vim.inspect(vim.lsp.buf.list_workspace_folders())) - end, bufopts) - vim.keymap.set('n', 'D', vim.lsp.buf.type_definition, bufopts) - vim.keymap.set('n', 'rn', vim.lsp.buf.rename, bufopts) - vim.keymap.set('n', 'ca', vim.lsp.buf.code_action, bufopts) - vim.keymap.set('n', 'gr', vim.lsp.buf.references, bufopts) - vim.keymap.set('n', 'f', function() vim.lsp.buf.format { async = true } end, bufopts) -end +If you want to, as an example, turn on auto-formatting, add `auto-format = true`: --- Configure `ruff-lsp`. --- See: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#ruff_lsp --- For the default config, along with instructions on how to customize the settings -require('lspconfig').ruff_lsp.setup { - on_attach = on_attach, - init_options = { - settings = { - -- Any extra CLI arguments for `ruff` go here. - args = {}, - } - } -} +```toml +[[language]] +name = "python" +language-servers = ["ruff", "pylsp"] +auto-format = true ``` -Ruff is also available as part of the [coc-pyright](https://github.com/fannheyward/coc-pyright) -extension for `coc.nvim`. +See the [Helix documentation](https://docs.helix-editor.com/languages.html) for more settings you can use here. -
-With the ALE plugin for (Neo)Vim. +You can pass settings into `ruff server` using `[language-server.ruff.config.settings]`. For example: -```vim -let g:ale_linters = { "python": ["ruff"] } -let g:ale_fixers = { -\ "python": ["black", "ruff"], -\} +```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 ``` -
- -
- -Ruff can also be integrated via - - efm - -in just a - - few lines. - - -
+By default, Ruff does not log anything to Helix. To enable logging, set the `RUFF_TRACE` environment variable +to either `messages` or `verbose`. -```yaml -tools: - python-ruff: &python-ruff - lint-command: "ruff check --config ~/myconfigs/linters/ruff.toml --quiet ${INPUT}" - lint-stdin: true - lint-formats: - - "%f:%l:%c: %m" - format-command: "ruff check --stdin-filename ${INPUT} --config ~/myconfigs/linters/ruff.toml --fix --exit-zero --quiet -" - format-stdin: true +```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. -
- -With the conform.nvim plugin for Neovim. - -
+To change the log level for Ruff (which is `info` by default), use the `logLevel` setting: -```lua -require("conform").setup({ - formatters_by_ft = { - python = { - -- To fix lint errors. - "ruff_fix", - -- To run the Ruff formatter. - "ruff_format", - }, - }, -}) +```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: -
- -With the nvim-lint plugin for Neovim. - +```toml +[language-server.ruff] +command = "ruff" +args = ["server", "--preview"] +environment = { "RUFF_TRACE" = "messages" } -```lua -require("lint").linters_by_ft = { - python = { "ruff" }, +[language-server.ruff.config.settings] +logLevel = "debug" +logFile = "~/.cache/helix/ruff.log" +``` + +The `logFile` path supports tildes and environment variables. + +## Kate (Official) + +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. ## PyCharm (External Tool) @@ -313,6 +282,63 @@ Alternatively, it can be used via the [Apheleia](https://github.com/radian-softw Ruff is also available via the [`textmate2-ruff-linter`](https://github.com/vigo/textmate2-ruff-linter) bundle for TextMate. +# Other Integrations + +## pre-commit + +Ruff can be used as a [pre-commit](https://pre-commit.com) hook via [`ruff-pre-commit`](https://github.com/astral-sh/ruff-pre-commit): + +```yaml +- repo: https://github.com/astral-sh/ruff-pre-commit + # Ruff version. + rev: v0.4.10 + hooks: + # Run the linter. + - id: ruff + # Run the formatter. + - id: ruff-format +``` + +To enable lint fixes, add the `--fix` argument to the lint hook: + +```yaml +- repo: https://github.com/astral-sh/ruff-pre-commit + # Ruff version. + rev: v0.4.10 + hooks: + # Run the linter. + - id: ruff + args: [ --fix ] + # Run the formatter. + - id: ruff-format +``` + +To run the hooks over Jupyter Notebooks too, add `jupyter` to the list of allowed filetypes: + +```yaml +- repo: https://github.com/astral-sh/ruff-pre-commit + # Ruff version. + rev: v0.4.10 + hooks: + # Run the linter. + - id: ruff + types_or: [ python, pyi, jupyter ] + args: [ --fix ] + # Run the formatter. + - id: ruff-format + types_or: [ python, pyi, jupyter ] +``` + +When running with `--fix`, Ruff's lint hook should be placed _before_ Ruff's formatter hook, and +_before_ Black, isort, and other formatting tools, as Ruff's fix behavior can output code changes +that require reformatting. + +When running without `--fix`, Ruff's formatter hook can be placed before or after Ruff's lint hook. + +(As long as your Ruff configuration avoids any [linter-formatter incompatibilities](formatter.md#conflicting-lint-rules), +`ruff format` should never introduce new lint errors, so it's safe to run Ruff's format hook _after_ +`ruff check --fix`.) + ## mdformat (Unofficial) [mdformat](https://mdformat.readthedocs.io/en/stable/users/plugins.html#code-formatter-plugins) is From 2fda0038d816352f919b446ba1305b2a446644ff Mon Sep 17 00:00:00 2001 From: Jane Lewis Date: Wed, 26 Jun 2024 15:32:06 -0700 Subject: [PATCH 2/5] Remove unavailable link --- docs/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations.md b/docs/integrations.md index 98532a01f9b16..06ff9035d820b 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -10,7 +10,7 @@ The Ruff language server, also known as `ruff server`, is what powers the diagno Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff), which supports fix actions, import sorting, and more. -By default, the extension will attempt to use the `ruff` executable installed on your local system, and will use a bundled executable if that's not available. If `ruff` is `v0.4.5` or later, the extension will automatically use `ruff server` - otherwise, it will use `ruff-lsp`. To configure this behavior, refer to the `languageServer` setting (add link here). +By default, the extension will attempt to use the `ruff` executable installed on your local system, and will use a bundled executable if that's not available. If `ruff` is `v0.4.5` or later, the extension will automatically use `ruff server` - otherwise, it will use `ruff-lsp`. To learn more about configuring the extension, and the settings available for the extension, refer to [Configuring Ruff](https://github.com/astral-sh/ruff-vscode/?tab=readme-ov-file#configuring-ruff) in the `ruff-vscode` documentation. From e7a7da9ae99bf1617ac42bde89f44e79ba3d8fa7 Mon Sep 17 00:00:00 2001 From: Jane Lewis Date: Fri, 28 Jun 2024 05:39:12 -0700 Subject: [PATCH 3/5] Reduce all headings and re-add a single top-level heading --- docs/integrations.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/integrations.md b/docs/integrations.md index 06ff9035d820b..acf0b344be5dd 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -1,12 +1,14 @@ -# Editor Integrations +# Integrations -## Ruff Language Server (`ruff server`) +## Editor Integrations + +### Ruff Language Server (`ruff server`) The Ruff language server, also known as `ruff server`, is what powers the diagnostic and formatting capabilities of Ruff's VS Code extension and other editors. It is a single, common backend for editor integrations built directly into Ruff, and a direct replacement for `ruff-lsp`, our previous language server. You can read more about `ruff server` in the [`v0.4.5` blog post](https://astral.sh/blog/ruff-v0.4.5). `ruff server` uses the LSP (Language Server Protocol), and as such works with any editor that supports this protocol. VS Code, Neovim, Helix, and Kate all have official, documented support for `ruff server`. Other editors may support the older `ruff-lsp` server - see the [Setup](https://github.com/astral-sh/ruff-lsp#setup) guide in `ruff-lsp` for more details. -## VS Code (Official) +### VS Code (Official) Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff), which supports fix actions, import sorting, and more. @@ -14,9 +16,9 @@ By default, the extension will attempt to use the `ruff` executable installed on To learn more about configuring the extension, and the settings available for the extension, refer to [Configuring Ruff](https://github.com/astral-sh/ruff-vscode/?tab=readme-ov-file#configuring-ruff) in the `ruff-vscode` documentation. -## Vim & Neovim (Official) +### Vim & Neovim (Official) -### Using `nvim-lspconfig` +#### 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). @@ -33,7 +35,7 @@ on how to configure the server from there. > > If you have the older language server (`ruff-lsp`) configured in Neovim, make sure to disable it to prevent any conflicts. -#### Tips +##### 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`: @@ -109,7 +111,7 @@ require('lspconfig').ruff.setup { The `logFile` path supports tildes and environment variables. -## Helix (Official) +### Helix (Official) 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`. @@ -211,7 +213,7 @@ logFile = "~/.cache/helix/ruff.log" The `logFile` path supports tildes and environment variables. -## Kate (Official) +### Kate (Official) 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). @@ -237,7 +239,7 @@ on how to configure the server from there. > > Kate's LSP Client plugin does not support multiple servers for the same language. -## PyCharm (External Tool) +### PyCharm (External Tool) Ruff can be installed as an [External Tool](https://www.jetbrains.com/help/pycharm/configuring-third-party-tools.html) in PyCharm. Open the Preferences pane, then navigate to "Tools", then "External Tools". From there, @@ -249,12 +251,12 @@ Ruff should then appear as a runnable action: ![Ruff as a runnable action](https://user-images.githubusercontent.com/1309177/193156026-732b0aaf-3dd9-4549-9b4d-2de6d2168a33.png) -## PyCharm (Unofficial) +### PyCharm (Unofficial) Ruff is also available as the [Ruff](https://plugins.jetbrains.com/plugin/20574-ruff) plugin on the IntelliJ Marketplace (maintained by @koxudaxi). -## Emacs (Unofficial) +### Emacs (Unofficial) Ruff is available as [`flymake-ruff`](https://melpa.org/#/flymake-ruff) on MELPA: @@ -277,14 +279,14 @@ Alternatively, it can be used via the [Apheleia](https://github.com/radian-softw (add-to-list 'apheleia-mode-alist '(python-ts-mode . ruff)) ``` -## TextMate (Unofficial) +### TextMate (Unofficial) Ruff is also available via the [`textmate2-ruff-linter`](https://github.com/vigo/textmate2-ruff-linter) bundle for TextMate. -# Other Integrations +## Other Integrations -## pre-commit +### pre-commit Ruff can be used as a [pre-commit](https://pre-commit.com) hook via [`ruff-pre-commit`](https://github.com/astral-sh/ruff-pre-commit): @@ -339,13 +341,13 @@ When running without `--fix`, Ruff's formatter hook can be placed before or afte `ruff format` should never introduce new lint errors, so it's safe to run Ruff's format hook _after_ `ruff check --fix`.) -## mdformat (Unofficial) +### mdformat (Unofficial) [mdformat](https://mdformat.readthedocs.io/en/stable/users/plugins.html#code-formatter-plugins) is capable of formatting code blocks within Markdown. The [`mdformat-ruff`](https://github.com/Freed-Wu/mdformat-ruff) plugin enables mdformat to format Python code blocks with Ruff. -## GitHub Actions +### GitHub Actions GitHub Actions has everything you need to run Ruff out-of-the-box: From 6034a4e0ba61c02cf2ab79eeb6e38c4446ac9660 Mon Sep 17 00:00:00 2001 From: Jane Lewis Date: Fri, 28 Jun 2024 06:27:37 -0700 Subject: [PATCH 4/5] Apply suggestions Co-authored-by: Charlie Marsh --- docs/integrations.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/integrations.md b/docs/integrations.md index acf0b344be5dd..7c26a9b30e4e8 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -4,15 +4,15 @@ ### Ruff Language Server (`ruff server`) -The Ruff language server, also known as `ruff server`, is what powers the diagnostic and formatting capabilities of Ruff's VS Code extension and other editors. It is a single, common backend for editor integrations built directly into Ruff, and a direct replacement for `ruff-lsp`, our previous language server. You can read more about `ruff server` in the [`v0.4.5` blog post](https://astral.sh/blog/ruff-v0.4.5). +The Ruff language server, also known as `ruff server`, powers the diagnostic and formatting capabilities of Ruff's VS Code extension and other editor integrations. It is a single, common backend built directly into Ruff, and a direct replacement for `ruff-lsp`, our previous language server. You can read more about `ruff server` in the [`v0.4.5` blog post](https://astral.sh/blog/ruff-v0.4.5). -`ruff server` uses the LSP (Language Server Protocol), and as such works with any editor that supports this protocol. VS Code, Neovim, Helix, and Kate all have official, documented support for `ruff server`. Other editors may support the older `ruff-lsp` server - see the [Setup](https://github.com/astral-sh/ruff-lsp#setup) guide in `ruff-lsp` for more details. +`ruff server` uses the LSP (Language Server Protocol), and as such works with any editor that supports this protocol. VS Code, Neovim, Helix, and Kate all have official, documented support for `ruff server`. Other editors may support the legacy `ruff-lsp` server; see the [`ruff-lsp` documentation](https://github.com/astral-sh/ruff-lsp#setup) for more. ### VS Code (Official) -Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff), which supports fix actions, import sorting, and more. +Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff), which supports code formatting, fix actions, import sorting, and more. -By default, the extension will attempt to use the `ruff` executable installed on your local system, and will use a bundled executable if that's not available. If `ruff` is `v0.4.5` or later, the extension will automatically use `ruff server` - otherwise, it will use `ruff-lsp`. +By default, the extension will attempt to use the `ruff` executable installed on your local system, and will use a bundled executable if that's not available. If `ruff` is `v0.4.5` or later, the extension will automatically use `ruff server`; otherwise, it will use fall back to `ruff-lsp`. To learn more about configuring the extension, and the settings available for the extension, refer to [Configuring Ruff](https://github.com/astral-sh/ruff-vscode/?tab=readme-ov-file#configuring-ruff) in the `ruff-vscode` documentation. @@ -73,7 +73,7 @@ require('lspconfig').pyright.setup { } ``` -By default, Ruff will not show any logs. To enable logging in Neovim, you'll need to set the `RUFF_TRACE` environment variable +To enable logging in Neovim, set the `RUFF_TRACE` environment variable to either `messages` or `verbose`: ```lua @@ -82,7 +82,7 @@ require('lspconfig').ruff.setup { } ``` -You can set the log level in `settings`: +You can then set the desired log level (e.g., `debug` vs. `warning`) in the extension `settings`: ```lua require('lspconfig').ruff.setup { @@ -124,7 +124,7 @@ command = "ruff" args = ["server", "--preview"] ``` -Then, you'll register the language server as the one to use with Python. +Next, register the language server for use in Python files. If you don't already have a language server registered to use with Python, add this to `languages.toml`: ```toml From 7f9c31720bf333906c038181c763c3be57482637 Mon Sep 17 00:00:00 2001 From: Jane Lewis Date: Fri, 28 Jun 2024 06:29:32 -0700 Subject: [PATCH 5/5] Apply ruff-vscode settings suggestion --- docs/integrations.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/integrations.md b/docs/integrations.md index 7c26a9b30e4e8..ef456a5b534e5 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -14,7 +14,21 @@ Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items By default, the extension will attempt to use the `ruff` executable installed on your local system, and will use a bundled executable if that's not available. If `ruff` is `v0.4.5` or later, the extension will automatically use `ruff server`; otherwise, it will use fall back to `ruff-lsp`. -To learn more about configuring the extension, and the settings available for the extension, refer to [Configuring Ruff](https://github.com/astral-sh/ruff-vscode/?tab=readme-ov-file#configuring-ruff) in the `ruff-vscode` documentation. +To configure Ruff to format, fix, and organize imports on-save, add the following to your `settings.json`: +```json +{ + "[python]": { + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll": "explicit", + "source.organizeImports": "explicit" + }, + "editor.defaultFormatter": "charliermarsh.ruff" + } +} +``` + +For more on configuring the extension, refer to the [ruff-vscode documentation](https://github.com/astral-sh/ruff-vscode/?tab=readme-ov-file#configuring-ruff). ### Vim & Neovim (Official)