Rework the documentation to incorporate the Ruff formatter #7732

charliermarsh · 2023-10-01T03:10:11Z

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 #7235.

Closes #7647.

charliermarsh · 2023-10-01T03:38:03Z

docs/formatter.md

+- [`bad-quotes-inline-string`](rules/bad-quotes-inline-string.md)
+- [`bad-quotes-multiline-string`](rules/bad-quotes-multiline-string.md)
+- [`bad-quotes-docstring`](rules/bad-quotes-docstring.md)
+- [`avoidable-escaped-quote`](rules/avoidable-escaped-quote.md)


These aren't necessarily conflicting with the formatter. The quote rules are probably consistent with it, assuming you have the same quote settings. And the trailing comma rules won't conflict with the formatter, they'll just end up changing the resulting formatting.

charliermarsh · 2023-10-01T03:38:42Z

docs/formatter.md

+
+This will likely be incorporated into Black's preview style ([#3823](https://github.com/psf/black/pull/3823)).
+
+<h4><code>global</code> and <code>nonlocal</code> names are broken across multiple lines by continuations</h4>


Using <h4> here ensures that this long list of intentional deviations is omitted from the table of contents on the left side of the page, which IMO is good. However, it also means they can't be permalinked, which IMO is bad...

Can you manually give them id? It's still not really accessible to users but at least it's possible if you know.

I decided to move them to their own page.

github-actions · 2023-10-01T03:53:24Z

PR Check Results

Ecosystem

✅ ecosystem check detected no changes.

konstin

📜 📜 📜

docs/configuration.md

docs/faq.md

docs/formatter.md

konstin · 2023-10-01T16:08:52Z

docs/formatter.md

+
+This will likely be incorporated into Black's preview style ([#3823](https://github.com/psf/black/pull/3823)).
+
+<h4><code>global</code> and <code>nonlocal</code> names are broken across multiple lines by continuations</h4>


Can you manually give them id? It's still not really accessible to users but at least it's possible if you know.

docs/linter.md

docs/tutorial.md

codspeed-hq · 2023-10-01T18:38:54Z

CodSpeed Performance Report

Merging #7732 will not alter performance

_{Comparing charlie/formatter-docs (27a56f6) with main (fa556d1)}

Summary

✅ 25 untouched benchmarks

docs/formatter.md

docs/formatter/black.md

README.md

docs/configuration.md

docs/faq.md

docs/formatter.md

scripts/generate_mkdocs.py

Adds documentation for using `ruff check . --fix` Uses the draft of the "Automatic fixes" section from #7732 and adds documentation for unsafe fixes, applicability levels, and #7841 I enabled admonitions because they're nice. We should use them more.

docs/configuration.md

docs/faq.md

docs/formatter.md

MichaReiser · 2023-10-18T00:58:09Z

We should add an example for how to exclude certain files from linting / formatting only #8000

README.md

docs/configuration.md

MichaReiser · 2023-10-20T01:01:29Z

README.md

@@ -208,26 +217,44 @@ exclude = [
 # Same as Black.
 line-length = 88


Suggested change

line-length = 88

line-length = 88

indent-width = 4

MichaReiser · 2023-10-20T01:02:02Z

docs/configuration.md

@@ -45,22 +37,45 @@ exclude = [
    "node_modules",
    "venv",
 ]
-per-file-ignores = {}

 # Same as Black.
 line-length = 88


Suggested change

line-length = 88

indent-width = 4

MichaReiser · 2023-10-20T01:02:10Z

docs/configuration.md

@@ -45,22 +37,45 @@ exclude = [
    "node_modules",
    "venv",
 ]
-per-file-ignores = {}

 # Same as Black.
 line-length = 88


Suggested change

line-length = 88

line-width = 88

MichaReiser · 2023-10-20T01:02:52Z

docs/configuration.md

+# ...but use a different line length.
+line-length = 100


Suggested change

# ...but use a different line length.

line-length = 100

# ...but use a different line width.

line-width = 100

docs/formatter.md

MichaReiser · 2023-10-20T01:05:21Z

docs/tutorial.md

 # Decrease the maximum line length to 79 characters.
 line-length = 79


Suggested change

# Decrease the maximum line length to 79 characters.

line-length = 79

# Decrease the maximum line width to 79.

line-width = 79

MichaReiser · 2023-10-20T01:30:10Z

docs/formatter.md

+formatter's treatment of import statements when set to non-default values:
+
+- [`lines-after-imports`](https://docs.astral.sh/ruff/settings/#isort-lines-after-imports)
+- [`lines-between-types`](https://docs.astral.sh/ruff/settings/#isort-lines-between-types)


Our internal configuration document mentions more conflicting rules and isort options. Are there reasons why you excluded some of the rules and options from here?

I'll add them, but it's the same confusion as in your PR that enables the warnings -- what constitutes a "conflict"?

I also added ISC001 and Q003, were those intentionally omitted?

charliermarsh · 2023-10-20T22:45:02Z

Made all changes except I haven't done the length to width tweaks yet, since that hasn't merged.

## Summary As a follow-up of #7732, use `tool.ruff.lint` in more places in documentations, tests and internal usages.

charliermarsh added the documentation Improvements or additions to documentation label Oct 1, 2023

charliermarsh force-pushed the charlie/formatter-docs branch 7 times, most recently from e81c509 to c64f374 Compare October 1, 2023 03:37

charliermarsh commented Oct 1, 2023

View reviewed changes

konstin approved these changes Oct 1, 2023

View reviewed changes

charliermarsh force-pushed the charlie/formatter-docs branch from c64f374 to 38289bc Compare October 1, 2023 18:28

T-256 reviewed Oct 2, 2023

View reviewed changes

docs/formatter.md Outdated Show resolved Hide resolved

charliermarsh force-pushed the charlie/formatter-docs branch 2 times, most recently from 72a64c6 to 72a1f4d Compare October 2, 2023 23:03

dhirschfeld reviewed Oct 3, 2023

View reviewed changes

docs/formatter/black.md Outdated Show resolved Hide resolved

dhruvmanila reviewed Oct 5, 2023

View reviewed changes

charliermarsh force-pushed the charlie/formatter-docs branch 2 times, most recently from 9fd6737 to 0b67439 Compare October 5, 2023 15:42

zanieb mentioned this pull request Oct 10, 2023

Add documentation for fixes #7901

Merged

echoix mentioned this pull request Oct 11, 2023

What's the best practice for a linter's custom args in CLI call to process the listed files for linting ? oxsecurity/megalinter#3000

Closed

charliermarsh force-pushed the charlie/formatter-docs branch from 0b67439 to a086cde Compare October 16, 2023 00:25

MichaReiser approved these changes Oct 16, 2023

View reviewed changes

MichaReiser reviewed Oct 19, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

MichaReiser reviewed Oct 19, 2023

View reviewed changes

docs/configuration.md Outdated Show resolved Hide resolved

MichaReiser reviewed Oct 20, 2023

View reviewed changes

charliermarsh force-pushed the charlie/formatter-docs branch 2 times, most recently from 7acc677 to c365de2 Compare October 20, 2023 22:44

charliermarsh enabled auto-merge (squash) October 20, 2023 22:46

charliermarsh force-pushed the charlie/formatter-docs branch 5 times, most recently from 2adc81f to cf8ba7a Compare October 20, 2023 22:50

charliermarsh disabled auto-merge October 20, 2023 22:50

charliermarsh force-pushed the charlie/formatter-docs branch 5 times, most recently from 527b370 to 27a56f6 Compare October 20, 2023 23:00

charliermarsh enabled auto-merge (squash) October 20, 2023 23:00

Rework the documentation to incorporate the Ruff formatter

27a56f6

charliermarsh merged commit f6d6200 into main Oct 20, 2023
15 checks passed

charliermarsh deleted the charlie/formatter-docs branch October 20, 2023 23:08

p-linnane mentioned this pull request Oct 24, 2023

ruff 0.1.2 Homebrew/homebrew-core#152273

Merged

mkniewallner mentioned this pull request Oct 28, 2023

Use tool.ruff.lint in more places #8317

Merged

zanieb pushed a commit that referenced this pull request Oct 28, 2023

Use tool.ruff.lint in more places (#8317)

317b6e8

## Summary As a follow-up of #7732, use `tool.ruff.lint` in more places in documentations, tests and internal usages.

abravalheri mentioned this pull request Jan 4, 2024

Apply more assorted Pyugrade suggestions pypa/setuptools#4125

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework the documentation to incorporate the Ruff formatter #7732

Rework the documentation to incorporate the Ruff formatter #7732

charliermarsh commented Oct 1, 2023 •

edited

charliermarsh Oct 1, 2023

charliermarsh Oct 1, 2023

konstin Oct 1, 2023

charliermarsh Oct 5, 2023

github-actions bot commented Oct 1, 2023 •

edited

konstin left a comment

konstin Oct 1, 2023

codspeed-hq bot commented Oct 1, 2023 •

edited

MichaReiser commented Oct 18, 2023

MichaReiser Oct 20, 2023

MichaReiser Oct 20, 2023

MichaReiser Oct 20, 2023

MichaReiser Oct 20, 2023

MichaReiser Oct 20, 2023

MichaReiser Oct 20, 2023 •

edited

charliermarsh Oct 20, 2023

charliermarsh Oct 20, 2023

charliermarsh commented Oct 20, 2023


		This will likely be incorporated into Black's preview style ([#3823](https://github.com/psf/black/pull/3823)).

		<h4><code>global</code> and <code>nonlocal</code> names are broken across multiple lines by continuations</h4>

		@@ -208,26 +217,44 @@ exclude = [
		# Same as Black.
		line-length = 88

		# Decrease the maximum line length to 79 characters.
		line-length = 79

Rework the documentation to incorporate the Ruff formatter #7732

Rework the documentation to incorporate the Ruff formatter #7732

Conversation

charliermarsh commented Oct 1, 2023 • edited

Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Oct 1, 2023 • edited

PR Check Results

Ecosystem

konstin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codspeed-hq bot commented Oct 1, 2023 • edited

Merging #7732 will not alter performance

Summary

MichaReiser commented Oct 18, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MichaReiser Oct 20, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

charliermarsh commented Oct 20, 2023

charliermarsh commented Oct 1, 2023 •

edited

github-actions bot commented Oct 1, 2023 •

edited

codspeed-hq bot commented Oct 1, 2023 •

edited

MichaReiser Oct 20, 2023 •

edited