mirror of
https://github.com/astral-sh/ruff.git
synced 2025-11-26 22:52:32 +00:00
Move editor integrations into MkDocs (#2983)
This commit is contained in:
Charlie Marsh
GitHub
parent
50ee14a418
commit
a0912deb2b
4 changed files with 219 additions and 226 deletions
225
README.md
225
README.md
|
|
@ -683,231 +683,6 @@ use of an autoformatter, like [Black](https://github.com/psf/black).
|
|||
For a complete enumeration, see the [list of rules](https://beta.ruff.rs/docs/rules/) in the
|
||||
Ruff documentation.
|
||||
|
||||
## Editor Integrations
|
||||
|
||||
<!-- Begin section: Editor Integrations -->
|
||||
|
||||
### VS Code (Official)
|
||||
|
||||
Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff),
|
||||
which supports autofix actions, import sorting, and more.
|
||||
|
||||
|
||||
|
||||
### Language Server Protocol (Official)
|
||||
|
||||
Ruff supports the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
|
||||
via the [`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp) Python package, available on
|
||||
[PyPI](https://pypi.org/project/ruff-lsp/).
|
||||
|
||||
[`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp) enables Ruff to be used with any editor that
|
||||
supports the Language Server Protocol, including [Neovim](https://github.com/charliermarsh/ruff-lsp#example-neovim),
|
||||
[Sublime Text](https://github.com/charliermarsh/ruff-lsp#example-sublime-text), Emacs, and more.
|
||||
|
||||
For example, 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`:
|
||||
|
||||
```lua
|
||||
-- See: https://github.com/neovim/nvim-lspconfig/tree/54eb2a070a4f389b1be0f98070f81d23e2b1a715#suggested-configuration
|
||||
local opts = { noremap=true, silent=true }
|
||||
vim.keymap.set('n', '<space>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', '<space>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 <c-x><c-o>
|
||||
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', '<C-k>', vim.lsp.buf.signature_help, bufopts)
|
||||
vim.keymap.set('n', '<space>wa', vim.lsp.buf.add_workspace_folder, bufopts)
|
||||
vim.keymap.set('n', '<space>wr', vim.lsp.buf.remove_workspace_folder, bufopts)
|
||||
vim.keymap.set('n', '<space>wl', function()
|
||||
print(vim.inspect(vim.lsp.buf.list_workspace_folders()))
|
||||
end, bufopts)
|
||||
vim.keymap.set('n', '<space>D', vim.lsp.buf.type_definition, bufopts)
|
||||
vim.keymap.set('n', '<space>rn', vim.lsp.buf.rename, bufopts)
|
||||
vim.keymap.set('n', '<space>ca', vim.lsp.buf.code_action, bufopts)
|
||||
vim.keymap.set('n', 'gr', vim.lsp.buf.references, bufopts)
|
||||
vim.keymap.set('n', '<space>f', function() vim.lsp.buf.format { async = true } end, bufopts)
|
||||
end
|
||||
|
||||
-- Configure `ruff-lsp`.
|
||||
local configs = require 'lspconfig.configs'
|
||||
if not configs.ruff_lsp then
|
||||
configs.ruff_lsp = {
|
||||
default_config = {
|
||||
cmd = { 'ruff-lsp' },
|
||||
filetypes = { 'python' },
|
||||
root_dir = require('lspconfig').util.find_git_ancestor,
|
||||
init_options = {
|
||||
settings = {
|
||||
args = {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
end
|
||||
require('lspconfig').ruff_lsp.setup {
|
||||
on_attach = on_attach,
|
||||
}
|
||||
```
|
||||
|
||||
Upon successful installation, you should see Ruff's diagnostics surfaced directly in your editor:
|
||||
|
||||
|
||||
|
||||
To use `ruff-lsp` with other editors, including Sublime Text and Helix, see the [`ruff-lsp` documentation](https://github.com/charliermarsh/ruff-lsp#installation-and-usage).
|
||||
|
||||
### Language Server Protocol (Unofficial)
|
||||
|
||||
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-ruff), both of which are
|
||||
installable from PyPI:
|
||||
|
||||
```shell
|
||||
pip install python-lsp-server python-lsp-ruff
|
||||
```
|
||||
|
||||
The LSP server can then be used with any editor that supports the Language Server Protocol.
|
||||
|
||||
For example, to use `python-lsp-ruff` with Neovim, add something like the following to your
|
||||
`init.lua`:
|
||||
|
||||
```lua
|
||||
require'lspconfig'.pylsp.setup {
|
||||
settings = {
|
||||
pylsp = {
|
||||
plugins = {
|
||||
ruff = {
|
||||
enabled = true
|
||||
},
|
||||
pycodestyle = {
|
||||
enabled = false
|
||||
},
|
||||
pyflakes = {
|
||||
enabled = false
|
||||
},
|
||||
mccabe = {
|
||||
enabled = false
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Vim & Neovim
|
||||
|
||||
Ruff can be integrated into any editor that supports the Language Server Protocol via [`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp)
|
||||
(see: [Language Server Protocol](#language-server-protocol-official)), including Vim and Neovim.
|
||||
|
||||
It's recommended that you use [`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp), the
|
||||
officially supported LSP server for Ruff.
|
||||
|
||||
However, Ruff is also available as part of the [coc-pyright](https://github.com/fannheyward/coc-pyright)
|
||||
extension for `coc.nvim`.
|
||||
|
||||
<details>
|
||||
<summary>With the <a href="https://github.com/dense-analysis/ale">ALE</a> plugin for (Neo)Vim.</summary>
|
||||
|
||||
```vim
|
||||
let g:ale_linters = { "python": ["ruff"] }
|
||||
let g:ale_fixers = {
|
||||
\ "python": ["black", "ruff"],
|
||||
\}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Ruff can also be integrated via <a href="https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#efm"><code>efm</code></a> in just a <a href="https://github.com/JafarAbdi/myconfigs/blob/6f0b6b2450e92ec8fc50422928cd22005b919110/efm-langserver/config.yaml#L14-L20">few lines</a>.</summary>
|
||||
<br>
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>For neovim users using <a href="https://github.com/jose-elias-alvarez/null-ls.nvim"><code>null-ls</code></a>, Ruff is already <a href="https://github.com/jose-elias-alvarez/null-ls.nvim">integrated</a>.</summary>
|
||||
<br>
|
||||
|
||||
```lua
|
||||
local null_ls = require("null-ls")
|
||||
|
||||
null_ls.setup({
|
||||
sources = {
|
||||
null_ls.builtins.formatting.ruff,
|
||||
null_ls.builtins.diagnostics.ruff,
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 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,
|
||||
add a new tool with the following configuration:
|
||||
|
||||
|
||||
|
||||
Ruff should then appear as a runnable action:
|
||||
|
||||
|
||||
|
||||
### PyCharm (Unofficial)
|
||||
|
||||
Ruff is also available as the [Ruff](https://plugins.jetbrains.com/plugin/20574-ruff) plugin on the
|
||||
IntelliJ Marketplace (maintained by @koxudaxi).
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
GitHub Actions has everything you need to run Ruff out-of-the-box:
|
||||
|
||||
```yaml
|
||||
name: CI
|
||||
on: push
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Install Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: "3.11"
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
python -m pip install --upgrade pip
|
||||
pip install ruff
|
||||
# Include `--format=github` to enable automatic inline annotations.
|
||||
- name: Run Ruff
|
||||
run: ruff check --format=github .
|
||||
```
|
||||
|
||||
<!-- End section: Editor Integrations -->
|
||||
|
||||
## FAQ
|
||||
|
||||
<!-- Begin section: FAQ -->
|
||||
|
|
|
|||
1
docs/.gitignore
vendored
1
docs/.gitignore
vendored
|
|
@ -1,3 +1,4 @@
|
|||
*
|
||||
!assets
|
||||
!requirements.txt
|
||||
!editor-integrations.md
|
||||
|
|
|
|||
218
docs/editor-integrations.md
Normal file
218
docs/editor-integrations.md
Normal file
|
|
@ -0,0 +1,218 @@
|
|||
### VS Code (Official)
|
||||
|
||||
Download the [Ruff VS Code extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff),
|
||||
which supports autofix actions, import sorting, and more.
|
||||
|
||||
|
||||
|
||||
### Language Server Protocol (Official)
|
||||
|
||||
Ruff supports the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
|
||||
via the [`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp) Python package, available on
|
||||
[PyPI](https://pypi.org/project/ruff-lsp/).
|
||||
|
||||
[`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp) enables Ruff to be used with any editor that
|
||||
supports the Language Server Protocol, including [Neovim](https://github.com/charliermarsh/ruff-lsp#example-neovim),
|
||||
[Sublime Text](https://github.com/charliermarsh/ruff-lsp#example-sublime-text), Emacs, and more.
|
||||
|
||||
For example, 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`:
|
||||
|
||||
```lua
|
||||
-- See: https://github.com/neovim/nvim-lspconfig/tree/54eb2a070a4f389b1be0f98070f81d23e2b1a715#suggested-configuration
|
||||
local opts = { noremap=true, silent=true }
|
||||
vim.keymap.set('n', '<space>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', '<space>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 <c-x><c-o>
|
||||
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', '<C-k>', vim.lsp.buf.signature_help, bufopts)
|
||||
vim.keymap.set('n', '<space>wa', vim.lsp.buf.add_workspace_folder, bufopts)
|
||||
vim.keymap.set('n', '<space>wr', vim.lsp.buf.remove_workspace_folder, bufopts)
|
||||
vim.keymap.set('n', '<space>wl', function()
|
||||
print(vim.inspect(vim.lsp.buf.list_workspace_folders()))
|
||||
end, bufopts)
|
||||
vim.keymap.set('n', '<space>D', vim.lsp.buf.type_definition, bufopts)
|
||||
vim.keymap.set('n', '<space>rn', vim.lsp.buf.rename, bufopts)
|
||||
vim.keymap.set('n', '<space>ca', vim.lsp.buf.code_action, bufopts)
|
||||
vim.keymap.set('n', 'gr', vim.lsp.buf.references, bufopts)
|
||||
vim.keymap.set('n', '<space>f', function() vim.lsp.buf.format { async = true } end, bufopts)
|
||||
end
|
||||
|
||||
-- Configure `ruff-lsp`.
|
||||
local configs = require 'lspconfig.configs'
|
||||
if not configs.ruff_lsp then
|
||||
configs.ruff_lsp = {
|
||||
default_config = {
|
||||
cmd = { 'ruff-lsp' },
|
||||
filetypes = { 'python' },
|
||||
root_dir = require('lspconfig').util.find_git_ancestor,
|
||||
init_options = {
|
||||
settings = {
|
||||
args = {}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
end
|
||||
require('lspconfig').ruff_lsp.setup {
|
||||
on_attach = on_attach,
|
||||
}
|
||||
```
|
||||
|
||||
Upon successful installation, you should see Ruff's diagnostics surfaced directly in your editor:
|
||||
|
||||
|
||||
|
||||
To use `ruff-lsp` with other editors, including Sublime Text and Helix, see the [`ruff-lsp` documentation](https://github.com/charliermarsh/ruff-lsp#installation-and-usage).
|
||||
|
||||
### Language Server Protocol (Unofficial)
|
||||
|
||||
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-ruff), both of which are
|
||||
installable from PyPI:
|
||||
|
||||
```shell
|
||||
pip install python-lsp-server python-lsp-ruff
|
||||
```
|
||||
|
||||
The LSP server can then be used with any editor that supports the Language Server Protocol.
|
||||
|
||||
For example, to use `python-lsp-ruff` with Neovim, add something like the following to your
|
||||
`init.lua`:
|
||||
|
||||
```lua
|
||||
require'lspconfig'.pylsp.setup {
|
||||
settings = {
|
||||
pylsp = {
|
||||
plugins = {
|
||||
ruff = {
|
||||
enabled = true
|
||||
},
|
||||
pycodestyle = {
|
||||
enabled = false
|
||||
},
|
||||
pyflakes = {
|
||||
enabled = false
|
||||
},
|
||||
mccabe = {
|
||||
enabled = false
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Vim & Neovim
|
||||
|
||||
Ruff can be integrated into any editor that supports the Language Server Protocol via [`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp)
|
||||
(see: [Language Server Protocol](#language-server-protocol-official)), including Vim and Neovim.
|
||||
|
||||
It's recommended that you use [`ruff-lsp`](https://github.com/charliermarsh/ruff-lsp), the
|
||||
officially supported LSP server for Ruff.
|
||||
|
||||
However, Ruff is also available as part of the [coc-pyright](https://github.com/fannheyward/coc-pyright)
|
||||
extension for `coc.nvim`.
|
||||
|
||||
<details>
|
||||
<summary>With the <a href="https://github.com/dense-analysis/ale">ALE</a> plugin for (Neo)Vim.</summary>
|
||||
|
||||
```vim
|
||||
let g:ale_linters = { "python": ["ruff"] }
|
||||
let g:ale_fixers = {
|
||||
\ "python": ["black", "ruff"],
|
||||
\}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Ruff can also be integrated via <a href="https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#efm"><code>efm</code></a> in just a <a href="https://github.com/JafarAbdi/myconfigs/blob/6f0b6b2450e92ec8fc50422928cd22005b919110/efm-langserver/config.yaml#L14-L20">few lines</a>.</summary>
|
||||
<br>
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>For neovim users using <a href="https://github.com/jose-elias-alvarez/null-ls.nvim"><code>null-ls</code></a>, Ruff is already <a href="https://github.com/jose-elias-alvarez/null-ls.nvim">integrated</a>.</summary>
|
||||
<br>
|
||||
|
||||
```lua
|
||||
local null_ls = require("null-ls")
|
||||
|
||||
null_ls.setup({
|
||||
sources = {
|
||||
null_ls.builtins.formatting.ruff,
|
||||
null_ls.builtins.diagnostics.ruff,
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 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,
|
||||
add a new tool with the following configuration:
|
||||
|
||||
|
||||
|
||||
Ruff should then appear as a runnable action:
|
||||
|
||||
|
||||
|
||||
### PyCharm (Unofficial)
|
||||
|
||||
Ruff is also available as the [Ruff](https://plugins.jetbrains.com/plugin/20574-ruff) plugin on the
|
||||
IntelliJ Marketplace (maintained by @koxudaxi).
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
GitHub Actions has everything you need to run Ruff out-of-the-box:
|
||||
|
||||
```yaml
|
||||
name: CI
|
||||
on: push
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Install Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: "3.11"
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
python -m pip install --upgrade pip
|
||||
pip install ruff
|
||||
# Include `--format=github` to enable automatic inline annotations.
|
||||
- name: Run Ruff
|
||||
run: ruff check --format=github .
|
||||
```
|
||||
|
|
@ -12,7 +12,6 @@ SECTIONS: list[tuple[str, str]] = [
|
|||
("Configuration", "configuration.md"),
|
||||
("Rules", "rules.md"),
|
||||
("Settings", "settings.md"),
|
||||
("Editor Integrations", "editor-integrations.md"),
|
||||
("FAQ", "faq.md"),
|
||||
("Acknowledgements", "acknowledgements.md"),
|
||||
]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue