648cca199b
## 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`
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# Features
|
|
|
|
This section provides a detailed overview of the features provided by the Ruff Language Server.
|
|
|
|
## Diagnostic Highlighting
|
|
|
|
Provide diagnostics for your Python code in real-time.
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/violation_hx.gif"
|
|
alt="Editing a file in Helix"
|
|
/>
|
|
|
|
## Dynamic Configuration
|
|
|
|
The server dynamically refreshes the diagnostics when a configuration file is changed in the
|
|
workspace, whether it's a `pyproject.toml`, `ruff.toml`, or `.ruff.toml` file.
|
|
|
|
The server relies on the file watching capabilities of the editor to detect changes to these files.
|
|
If an editor does not support file watching, the server will not be able to detect
|
|
changes to the configuration file and thus will not refresh the diagnostics.
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/config_reload_vscode.gif"
|
|
alt="Editing a `pyproject.toml` configuration file in VS Code"
|
|
/>
|
|
|
|
## Formatting
|
|
|
|
Provide code formatting for your Python code. The server can format an entire document or a specific
|
|
range of lines.
|
|
|
|
The VS Code extension provides the `Ruff: Format Document` command to format an entire document.
|
|
In VS Code, the range formatting can be triggered by selecting a range of lines, right-clicking, and
|
|
selecting `Format Selection` from the context menu.
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/format_vscode.gif"
|
|
alt="Formatting a document in VS Code"
|
|
/>
|
|
|
|
## Code Actions
|
|
|
|
Code actions are context-sensitive suggestions that can help you fix issues in your code. They are
|
|
usually triggered by a shortcut or by clicking a light bulb icon in the editor. The Ruff Language
|
|
Server provides the following code actions:
|
|
|
|
- Apply a quick fix for a diagnostic that has a fix available (e.g., removing an unused import).
|
|
- Ignore a diagnostic with a `# noqa` comment.
|
|
- Apply all quick fixes available in the document.
|
|
- Organize imports in the document.
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/code_action_hx.gif"
|
|
alt="Applying a quick fix in Helix"
|
|
/>
|
|
|
|
You can even run these actions on-save. For example, to fix all issues and organize imports on save
|
|
in VS Code, add the following to your `settings.json`:
|
|
|
|
```json
|
|
{
|
|
"[python]": {
|
|
"editor.codeActionsOnSave": {
|
|
"source.fixAll.ruff": "explicit",
|
|
"source.organizeImports.ruff": "explicit"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Fix Safety
|
|
|
|
Ruff's automatic fixes are labeled as "safe" and "unsafe". By default, the "Fix all" action will not
|
|
apply unsafe fixes. However, unsafe fixes can be applied manually with the "Quick fix" action.
|
|
Application of unsafe fixes when using "Fix all" can be enabled by setting `unsafe-fixes = true` in
|
|
your Ruff configuration file.
|
|
|
|
See the [Ruff fix documentation](https://docs.astral.sh/ruff/linter/#fix-safety) for more details on
|
|
how fix safety works.
|
|
|
|
## Hover
|
|
|
|
The server can provide the rule documentation when focusing over a NoQA code in the comment.
|
|
Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/hover_vscode.gif"
|
|
alt="Hovering over a noqa code in VS Code"
|
|
/>
|
|
|
|
## Jupyter Notebook
|
|
|
|
Similar to Ruff's CLI, the Ruff Language Server fully supports Jupyter Notebook files with all the
|
|
capabilities available to Python files.
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/ipynb_editing_vscode.gif"
|
|
alt="Editing multiple Jupyter Notebook cells in VS Code"
|
|
/>
|
|
|
|
<img
|
|
src="https://astral.sh/static/GIF/v0.4.5/ipynb_range_format_vscode.gif"
|
|
alt="Formatting a selection within a Jupyter Notebook cell in VS Code"
|
|
/>
|