mirrors/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-08-04 18:58:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Rework the documentation to incorporate the Ruff formatter (#7732)

Browse source 
## Summary

This PR updates our documentation for the upcoming formatter release.

Broadly, the documentation is now structured as follows:

- Overview
- Tutorial
- Installing Ruff
- The Ruff Linter
    - Overview
    - `ruff check`
    - Rule selection
    - Error suppression
    - Exit codes
- The Ruff Formatter
    - Overview
    - `ruff format`
    - Philosophy
    - Configuration
    - Format suppression
    - Exit codes
    - Black compatibility
        - Known deviations
- Configuring Ruff
    - pyproject.toml
    - File discovery
    - Configuration discovery
    - CLI
    - Shell autocompletion
- Preview
- Rules
- Settings
- Integrations
    - `pre-commit`
    - VS Code
    - LSP
    - PyCharm
    - GitHub Actions
- FAQ
- Contributing

The major changes include:

- Removing the "Usage" section from the docs, and instead folding that
information into "Integrations" and the new Linter and Formatter
sections.
- Breaking up "Configuration" into "Configuring Ruff" (for generic
configuration), and new Linter- and Formatter-specific sections.
- Updating all example configurations to use `[tool.ruff.lint]` and
`[tool.ruff.format]`.

My suggestion is to pull and build the docs locally, and review by
reading them in the browser rather than trying to parse all the code
changes.

Closes https://github.com/astral-sh/ruff/issues/7235.

Closes https://github.com/astral-sh/ruff/issues/7647.
This commit is contained in:
Charlie Marsh 2023-10-20 19:08:26 -04:00 • committed by GitHub
parent fa556d1c74
commit f6d6200aae
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 1593 additions and 572 deletions
Download patch file Download diff file Expand all files Collapse all files

101
docs/tutorial.md
View file

@ -1,11 +1,17 @@
# Tutorial
This tutorial will walk you through the process of integrating Ruff into your project. For a more
detailed overview, see [_Configuration_](configuration.md).
This tutorial will walk you through the process of integrating Ruff's linter and formatter into
your project. For a more detailed overview, see [_Configuring Ruff_](configuration.md).
## Getting Started
Let's assume that our project structure looks like:
To start, we'll install Ruff through PyPI (or with your [preferred package manager](installation.md)):
```shell
pip install ruff
```
Let's then assume that our project structure looks like:
```text
numbers
@ -13,7 +19,7 @@ numbers
└── numbers.py
```
Where `numbers.py` contains the following code:
...where `numbers.py` contains the following code:
```py
from typing import Iterable
@ -23,16 +29,13 @@ import os
def sum_even_numbers(numbers: Iterable[int]) -> int:
"""Given an iterable of integers, return the sum of all even numbers in the iterable."""
return sum(num for num in numbers if num % 2 == 0)
return sum(
num for num in numbers
if num % 2 == 0
)
```
To start, we'll install Ruff through PyPI (or with your [preferred package manager](installation.md)):
```shell
> pip install ruff
```
We can then run Ruff over our project via `ruff check`:
We can run the Ruff linter over our project via `ruff check`:
```shell
❯ ruff check .
@ -62,7 +65,34 @@ Running `git diff` shows the following:
def sum_even_numbers(numbers: Iterable[int]) -> int:
"""Given an iterable of integers, return the sum of all even numbers in the iterable."""
return sum(num for num in numbers if num % 2 == 0)
return sum(
num for num in numbers
if num % 2 == 0
)
```
Now that our project is passing `ruff check`, we can run the Ruff formatter via `ruff format`:
```shell
❯ ruff format .
1 file reformatted
```
Running `git diff` shows that the `sum` call was reformatted to fit within the default 88-character
line length limit:
```diff
--- a/numbers.py
+++ b/numbers.py
@@ -3,7 +3,4 @@ from typing import Iterable
def sum_even_numbers(numbers: Iterable[int]) -> int:
"""Given an iterable of integers, return the sum of all even numbers in the iterable."""
- return sum(
- num for num in numbers
- if num % 2 == 0
- )
+ return sum(num for num in numbers if num % 2 == 0)
```
Thus far, we've been using Ruff's default configuration. Let's take a look at how we can customize
@ -73,19 +103,21 @@ Ruff's behavior.
To determine the appropriate settings for each Python file, Ruff looks for the first
`pyproject.toml`, `ruff.toml`, or `.ruff.toml` file in the file's directory or any parent directory.
Let's create a `pyproject.toml` file in our project's root directory:
To configure Ruff, let's create a `pyproject.toml` file in our project's root directory:
```toml
[tool.ruff]
# Set the maximum line length to 79 characters.
line-length = 79
[tool.ruff.linter]
# Add the `line-too-long` rule to the enforced rule set. By default, Ruff omits rules that
# overlap with the use of a formatter, like Black, but we can override this behavior by
# explicitly adding the rule.
extend-select = ["E501"]
# Set the maximum line length to 79 characters.
line-length = 79
```
Running Ruff again, we can see that it now enforces a line length of 79 characters:
Running Ruff again, we see that it now enforces a maximum line width, with a limit of 79 characters:
```shell
❯ ruff check .
@ -102,10 +134,12 @@ specifically, we'll want to make note of the minimum supported Python version:
requires-python = ">=3.10"
[tool.ruff]
# Add the `line-too-long` rule to the enforced rule set.
extend-select = ["E501"]
# Set the maximum line length to 79 characters.
line-length = 79
[tool.ruff.linter]
# Add the `line-too-long` rule to the enforced rule set.
extend-select = ["E501"]
```
### Rule Selection
@ -115,7 +149,7 @@ determining the right set of rules will depend on your project's needs: some rul
strict, some are framework-specific, and so on.
By default, Ruff enables Flake8's `F` rules, along with a subset of the `E` rules, omitting any
stylistic rules that overlap with the use of a formatter, like
stylistic rules that overlap with the use of a formatter, like `ruff format` or
[Black](https://github.com/psf/black).
If you're introducing a linter for the first time, **the default rule set is a great place to
@ -130,7 +164,7 @@ rules, we can set our `pyproject.toml` to the following:
[project]
requires-python = ">=3.10"
[tool.ruff]
[tool.ruff.linter]
extend-select = [
"UP", # pyupgrade
]
@ -153,13 +187,13 @@ all functions have docstrings:
[project]
requires-python = ">=3.10"
[tool.ruff]
[tool.ruff.linter]
extend-select = [
"UP", # pyupgrade
"D", # pydocstyle
]
[tool.ruff.pydocstyle]
[tool.ruff.linter.pydocstyle]
convention = "google"
```
@ -188,7 +222,7 @@ def sum_even_numbers(numbers: Iterable[int]) -> int:
return sum(num for num in numbers if num % 2 == 0)
```
Running Ruff again, we'll see that it no longer flags the `Iterable` import:
Running `ruff check` again, we'll see that it no longer flags the `Iterable` import:
```shell
❯ ruff check .
@ -210,7 +244,7 @@ def sum_even_numbers(numbers: Iterable[int]) -> int:
return sum(num for num in numbers if num % 2 == 0)
```
For more in-depth instructions on ignoring errors, see [_Configuration_](configuration.md#error-suppression).
For more in-depth instructions on ignoring errors, please see [_Error suppression_](linter.md#error-suppression).
### Adding Rules
@ -241,24 +275,27 @@ index b9291c5ca..b9f15b8c1 100644
def sum_even_numbers(numbers: Iterable[int]) -> int:
```
## Continuous Integration
## Integrations
This tutorial has focused on Ruff's command-line interface, but Ruff can also be used as a
[pre-commit](https://pre-commit.com) hook:
[pre-commit](https://pre-commit.com) hook via [`ruff-pre-commit`](https://github.com/astral-sh/ruff-pre-commit):
```yaml
# Run the Ruff linter.
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.1.1
hooks:
- id: ruff
# Run the Ruff formatter.
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.0.291
hooks:
- id: ruff-format
```
See [_Usage_](usage.md) for more.
## Editor Integrations
Ruff can also be used as a [VS Code extension](https://github.com/astral-sh/ruff-vscode) or
alongside any other editor through the [Ruff LSP](https://github.com/astral-sh/ruff-lsp).
See [_Editor Integrations_](editor-integrations.md).
For more, see [_Integrations_](integrations.md).