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`
3.4 KiB
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.
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.
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.
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
# noqacomment. - Apply all quick fixes available in the document.
- Organize imports in the document.
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:
{
"[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 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.
Jupyter Notebook
Similar to Ruff's CLI, the Ruff Language Server fully supports Jupyter Notebook files with all the capabilities available to Python files.
