language-servers/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-09-24 19:12:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

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

32
crates/ruff_python_formatter/README.md
View file

@ -176,7 +176,7 @@ original intent, at the cost of retaining additional vertical space.
This deviation only impacts unformatted code, in that Ruff's output should not deviate for code that
has already been formatted by Black.
### Pragma comments are ignored when computing line width
#### Pragma comments are ignored when computing line width
Pragma comments (`# type`, `# noqa`, `# pyright`, `# pylint`, etc.) are ignored when computing the width of a line.
This prevents Ruff from moving pragma comments around, thereby modifying their meaning and behavior:
@ -209,14 +209,14 @@ on both `first()` and `second()`:
]
```
### Line width vs. line length
#### Line width vs. line length
Ruff uses the Unicode width of a line to determine if a line fits. Black's stable style uses
character width, while Black's preview style uses Unicode width for strings ([#3445](https://github.com/psf/black/pull/3445)),
and character width for all other tokens. Ruff's behavior is closer to Black's preview style than
Black's stable style, although Ruff _also_ uses Unicode width for identifiers and comments.
### Walruses in slice expressions
#### Walruses in slice expressions
Black avoids inserting space around `:=` operators within slices. For example, the following adheres
to Black stable style:
@ -241,7 +241,7 @@ x[y := 1]
This will likely be incorporated into Black's preview style ([#3823](https://github.com/psf/black/pull/3823)).
### `global` and `nonlocal` names are broken across multiple lines by continuations
#### `global` and `nonlocal` names are broken across multiple lines by continuations
If a `global` or `nonlocal` statement includes multiple names, and exceeds the configured line
width, Ruff will break them across multiple lines using continuations:
@ -259,7 +259,7 @@ global \
analyze_size_model
```
### Newlines are inserted after all class docstrings
#### Newlines are inserted after all class docstrings
Black typically enforces a single newline after a class docstring. However, it does not apply such
formatting if the docstring is single-quoted rather than triple-quoted, while Ruff enforces a
@ -289,7 +289,7 @@ class IntFromGeom(GEOSFuncFactory):
errcheck = staticmethod(check_minus_one)
```
### Trailing own-line comments on imports are not moved to the next line
#### Trailing own-line comments on imports are not moved to the next line
Black enforces a single empty line between an import and a trailing own-line comment. Ruff leaves
such comments in-place:
@ -315,7 +315,7 @@ import os
import sys
```
### Parentheses around awaited collections are not preserved
#### Parentheses around awaited collections are not preserved
Black preserves parentheses around awaited collections:
@ -333,7 +333,7 @@ This is more consistent to the formatting of other awaited expressions: Ruff and
remove parentheses around, e.g., `await (1)`, only retaining them when syntactically required,
as in, e.g., `await (x := 1)`.
### Implicit string concatenations in attribute accesses ([#7052](https://github.com/astral-sh/ruff/issues/7052))
#### Implicit string concatenations in attribute accesses ([#7052](https://github.com/astral-sh/ruff/issues/7052))
Given the following unformatted code:
@ -375,7 +375,7 @@ In general, Black splits implicit string concatenations over multiple lines more
even if those concatenations _can_ fit on a single line. Ruff instead avoids splitting such
concatenations unless doing so is necessary to fit within the configured line width.
### Own-line comments on expressions don't cause the expression to expand ([#7314](https://github.com/astral-sh/ruff/issues/7314))
#### Own-line comments on expressions don't cause the expression to expand ([#7314](https://github.com/astral-sh/ruff/issues/7314))
Given an expression like:
@ -406,7 +406,7 @@ initial formatting:
)
```
### Tuples are parenthesized when expanded ([#7317](https://github.com/astral-sh/ruff/issues/7317))
#### Tuples are parenthesized when expanded ([#7317](https://github.com/astral-sh/ruff/issues/7317))
Ruff tends towards parenthesizing tuples (with a few exceptions), while Black tends to remove tuple
parentheses more often.
@ -454,7 +454,7 @@ for a, f(
pass
```
### Single-element tuples are always parenthesized
#### Single-element tuples are always parenthesized
Ruff always inserts parentheses around single-element tuples, while Black will omit them in some
cases:
@ -473,7 +473,7 @@ cases:
Adding parentheses around single-element tuples adds visual distinction and helps avoid "accidental"
tuples created by extraneous trailing commas (see, e.g., [#17181](https://github.com/django/django/pull/17181)).
### Trailing commas are inserted when expanding a function definition with a single argument ([#7323](https://github.com/astral-sh/ruff/issues/7323))
#### Trailing commas are inserted when expanding a function definition with a single argument ([#7323](https://github.com/astral-sh/ruff/issues/7323))
When a function definition with a single argument is expanded over multiple lines, Black
will add a trailing comma in some cases, depending on whether the argument includes a type
@ -506,7 +506,7 @@ def func(
Ruff will instead insert a trailing comma in all such cases for consistency.
### Parentheses around call-chain assignment values are not preserved ([#7320](https://github.com/astral-sh/ruff/issues/7320))
#### Parentheses around call-chain assignment values are not preserved ([#7320](https://github.com/astral-sh/ruff/issues/7320))
Given:
@ -539,7 +539,7 @@ def update_emission_strength():
value = self.emission_strength * 2
```
### Type annotations may be parenthesized when expanded ([#7315](https://github.com/astral-sh/ruff/issues/7315))
#### Type annotations may be parenthesized when expanded ([#7315](https://github.com/astral-sh/ruff/issues/7315))
Black will avoid parenthesizing type annotations in an annotated assignment, while Ruff will insert
parentheses in some cases.
@ -561,7 +561,7 @@ StartElementHandler: (
)
```
### Call chain calls break differently ([#7051](https://github.com/astral-sh/ruff/issues/7051))
#### Call chain calls break differently ([#7051](https://github.com/astral-sh/ruff/issues/7051))
Black occasionally breaks call chains differently than Ruff; in particular, Black occasionally
expands the arguments for the last call in the chain, as in:
@ -630,7 +630,7 @@ df.drop(columns=["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]).drop_duplicates(a).rename
).to_csv(path / "aaaaaa.csv", index=False).other(a)
```
### Expressions with (non-pragma) trailing comments are split more often ([#7823](https://github.com/astral-sh/ruff/issues/7823))
#### Expressions with (non-pragma) trailing comments are split more often ([#7823](https://github.com/astral-sh/ruff/issues/7823))
Both Ruff and Black will break the following expression over multiple lines, since it then allows
the expression to fit within the configured line width: