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.9 KiB
Integrations
GitHub Actions
GitHub Actions has everything you need to run Ruff out-of-the-box:
name: CI
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install ruff
# Update output format to enable automatic inline annotations.
- name: Run Ruff
run: ruff check --output-format=github .
Ruff can also be used as a GitHub Action via ruff-action.
By default, ruff-action runs as a pass-fail test to ensure that a given repository doesn't contain
any lint rule violations as per its configuration.
However, under-the-hood, ruff-action installs and runs ruff directly, so it can be used to
execute any supported ruff command (e.g., ruff check --fix).
ruff-action supports all GitHub-hosted runners, and can be used with any published Ruff version
(i.e., any version available on PyPI).
To use ruff-action, create a file (e.g., .github/workflows/ruff.yml) inside your repository
with:
name: Ruff
on: [ push, pull_request ]
jobs:
ruff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: chartboost/ruff-action@v1
Alternatively, you can include ruff-action as a step in any other workflow file:
- uses: chartboost/ruff-action@v1
ruff-action accepts optional configuration parameters via with:, including:
version: The Ruff version to install (default: latest).args: The command-line arguments to pass to Ruff (default:"check").src: The source paths to pass to Ruff (default:".").
For example, to run ruff check --select B ./src using Ruff version 0.0.259:
- uses: chartboost/ruff-action@v1
with:
version: 0.0.259
args: check --select B
src: "./src"
pre-commit
Ruff can be used as a pre-commit hook via ruff-pre-commit:
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.5.2
hooks:
# Run the linter.
- id: ruff
# Run the formatter.
- id: ruff-format
To enable lint fixes, add the --fix argument to the lint hook:
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.5.2
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:
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.5.2
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,
ruff format should never introduce new lint errors, so it's safe to run Ruff's format hook after
ruff check --fix.)
mdformat
mdformat is
capable of formatting code blocks within Markdown. The mdformat-ruff
plugin enables mdformat to format Python code blocks with Ruff.