From f2f2e759c79adbe4ed98e681a7cc08206af7775c Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Sat, 28 Oct 2023 19:25:38 -0700 Subject: [PATCH] Add a note on line-too-long to the formatter docs (#8314) Suggested here: https://github.com/astral-sh/ruff/discussions/7310#discussioncomment-7410638. --- docs/faq.md | 14 ++++++++------ docs/formatter.md | 7 ++++++- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 2194b09c25e18..257da168baf2d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -3,16 +3,18 @@ ## Is the Ruff linter compatible with Black? Yes. The Ruff linter is compatible with [Black](https://github.com/psf/black) out-of-the-box, as -long as the `line-length` setting is consistent between the two. +long as the [`line-length`](settings.md#line-length) setting is consistent between the two. Ruff is designed to be used alongside a formatter (like Ruff's own formatter, or Black) and, as such, will defer implementing stylistic rules that are obviated by automated formatting. -Note that Ruff and Black treat line-length enforcement a little differently. Black makes a -best-effort attempt to adhere to the `line-length`, but avoids automatic line-wrapping in some cases -(e.g., within comments). Ruff, on the other hand, will flag rule `E501` for any line that exceeds -the `line-length` setting. As such, if `E501` is enabled, Ruff can still trigger line-length -violations even when Black is enabled. +Note that Ruff's linter and Black treat line-length enforcement a little differently. Black, like +Ruff's formatter, makes a best-effort attempt to adhere to the +[`line-length`](settings.md#line-length), but avoids automatic line-wrapping in some cases (e.g., +within comments). Ruff, on the other hand, will flag [`line-too-long`](rules/line-too-long.md) +(`E501`) for any line that exceeds the [`line-length`](settings.md#line-length) setting. As such, if +[`line-too-long`](rules/line-too-long.md) (`E501`) is enabled, Ruff can still trigger line-length +violations even when Black or `ruff format` is enabled. ## How does Ruff's formatter compare to Black? diff --git a/docs/formatter.md b/docs/formatter.md index c6b84524eef2a..79279139199af 100644 --- a/docs/formatter.md +++ b/docs/formatter.md @@ -183,7 +183,7 @@ some rules that, when enabled, can cause conflicts with the formatter, leading t behavior. When configured appropriately, the goal of Ruff's formatter-linter compatibility is such that running the formatter should never introduce new lint errors. -As such, when using Ruff as a formatter, we recommend avoiding the following lint rules: +When using Ruff as a formatter, we recommend avoiding the following lint rules: - [`tab-indentation`](rules/tab-indentation.md) (`W191`) - [`indentation-with-invalid-multiple`](rules/indentation-with-invalid-multiple.md) (`E111`) @@ -200,6 +200,11 @@ As such, when using Ruff as a formatter, we recommend avoiding the following lin - [`single-line-implicit-string-concatenation`](rules/single-line-implicit-string-concatenation.md) (`ISC001`) - [`multi-line-implicit-string-concatenation`](rules/multi-line-implicit-string-concatenation.md) (`ISC002`) +While the [`line-too-long`](rules/line-too-long.md) (`E501`) rule _can_ be used alongside the +formatter, the formatter only makes a best-effort attempt to wrap lines at the configured +[`line-length`](settings.md#line-length). As such, formatted code _may_ exceed the line length, +leading to [`line-too-long`](rules/line-too-long.md) (`E501`) errors. + None of the above are included in Ruff's default configuration. However, if you've enabled any of these rules or their parent categories (like `Q`), we recommend disabling them via the linter's [`ignore`](settings.md#ignore) setting.