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

## 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.
astral-sh · Oct 20, 2023 · f6d6200 · f6d6200
1 parent fa556d1
commit f6d6200
Show file tree

Hide file tree

Showing 17 changed files with 1,589 additions and 568 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -24,6 +24,10 @@ repos:
         additional_dependencies:
           - mdformat-mkdocs
           - mdformat-admon
+        exclude: |
+          (?x)^(
+            docs/formatter/black.md
+          )$
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.33.0

diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 
 [**Discord**](https://discord.gg/c9MhzV8aU5) | [**Docs**](https://docs.astral.sh/ruff/) | [**Playground**](https://play.ruff.rs/)
 
-An extremely fast Python linter, written in Rust.
+An extremely fast Python linter and code formatter, written in Rust.
 
 <p align="center">
   <picture align="center">
@@ -24,28 +24,27 @@ An extremely fast Python linter, written in Rust.
   <i>Linting the CPython codebase from scratch.</i>
 </p>
 
-- ⚡️ 10-100x faster than existing linters
+- ⚡️ 10-100x faster than existing linters (like Flake8) and formatters (like Black)
 - 🐍 Installable via `pip`
 - 🛠️ `pyproject.toml` support
 - 🤝 Python 3.12 compatibility
+- ⚖️ Drop-in parity with [Flake8](https://docs.astral.sh/ruff/faq/#how-does-ruff-compare-to-flake8), isort, and Black
 - 📦 Built-in caching, to avoid re-analyzing unchanged files
 - 🔧 Fix support, for automatic error correction (e.g., automatically remove unused imports)
-- 📏 Over [700 built-in rules](https://docs.astral.sh/ruff/rules/)
-- ⚖️ [Near-parity](https://docs.astral.sh/ruff/faq/#how-does-ruff-compare-to-flake8) with the
-    built-in Flake8 rule set
-- 🔌 Native re-implementations of dozens of Flake8 plugins, like flake8-bugbear
-- ⌨️ First-party [editor integrations](https://docs.astral.sh/ruff/editor-integrations/) for
+- 📏 Over [700 built-in rules](https://docs.astral.sh/ruff/rules/), with native re-implementations
+    of popular Flake8 plugins, like flake8-bugbear
+- ⌨️ First-party [editor integrations](https://docs.astral.sh/ruff/integrations/) for
     [VS Code](https://github.com/astral-sh/ruff-vscode) and [more](https://github.com/astral-sh/ruff-lsp)
 - 🌎 Monorepo-friendly, with [hierarchical and cascading configuration](https://docs.astral.sh/ruff/configuration/#pyprojecttoml-discovery)
 
 Ruff aims to be orders of magnitude faster than alternative tools while integrating more
 functionality behind a single, common interface.
 
 Ruff can be used to replace [Flake8](https://pypi.org/project/flake8/) (plus dozens of plugins),
-[isort](https://pypi.org/project/isort/), [pydocstyle](https://pypi.org/project/pydocstyle/),
-[yesqa](https://github.com/asottile/yesqa), [eradicate](https://pypi.org/project/eradicate/),
-[pyupgrade](https://pypi.org/project/pyupgrade/), and [autoflake](https://pypi.org/project/autoflake/),
-all while executing tens or hundreds of times faster than any individual tool.
+[Black](https://github.com/psf/black), [isort](https://pypi.org/project/isort/),
+[pydocstyle](https://pypi.org/project/pydocstyle/), [pyupgrade](https://pypi.org/project/pyupgrade/),
+[autoflake](https://pypi.org/project/autoflake/), and more, all while executing tens or hundreds of
+times faster than any individual tool.
 
 Ruff is extremely actively developed and used in major open-source projects like:
 
@@ -126,23 +125,41 @@ and with [a variety of other package managers](https://docs.astral.sh/ruff/insta
 
 ### Usage
 
-To run Ruff, try any of the following:
+To run Ruff as a linter, try any of the following:
 
 ```shell
-ruff check .                        # Lint all files in the current directory (and any subdirectories)
-ruff check path/to/code/            # Lint all files in `/path/to/code` (and any subdirectories)
-ruff check path/to/code/*.py        # Lint all `.py` files in `/path/to/code`
-ruff check path/to/code/to/file.py  # Lint `file.py`
+ruff check .                        # Lint all files in the current directory (and any subdirectories).
+ruff check path/to/code/            # Lint all files in `/path/to/code` (and any subdirectories).
+ruff check path/to/code/*.py        # Lint all `.py` files in `/path/to/code`.
+ruff check path/to/code/to/file.py  # Lint `file.py`.
+ruff check @arguments.txt           # Lint using an input file, treating its contents as newline-delimited command-line arguments.
 ```
 
-Ruff can also be used as a [pre-commit](https://pre-commit.com) hook:
+Or, to run Ruff as a formatter:
+
+```shell
+ruff format .                        # Format all files in the current directory (and any subdirectories).
+ruff format path/to/code/            # Format all files in `/path/to/code` (and any subdirectories).
+ruff format path/to/code/*.py        # Format all `.py` files in `/path/to/code`.
+ruff format path/to/code/to/file.py  # Format `file.py`.
+ruff format @arguments.txt           # Format using an input file, treating its contents as newline-delimited command-line arguments.
+```
+
+Ruff can also be used as a [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
 ```
 
 Ruff can also be used as a [VS Code extension](https://github.com/astral-sh/ruff-vscode) or
@@ -168,18 +185,10 @@ Ruff can be configured through a `pyproject.toml`, `ruff.toml`, or `.ruff.toml`
 [_Configuration_](https://docs.astral.sh/ruff/configuration/), or [_Settings_](https://docs.astral.sh/ruff/settings/)
 for a complete list of all configuration options).
 
-If left unspecified, the default configuration is equivalent to:
+If left unspecified, Ruff's default configuration is equivalent to:
 
 ```toml
 [tool.ruff]
-# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
-select = ["E4", "E7", "E9", "F"]
-ignore = []
-
-# Allow fix for all enabled rules (when `--fix`) is provided.
-fixable = ["A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "T", "W", "ANN", "ARG", "BLE", "COM", "DJ", "DTZ", "EM", "ERA", "EXE", "FBT", "ICN", "INP", "ISC", "NPY", "PD", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "SIM", "SLF", "TCH", "TID", "TRY", "UP", "YTT"]
-unfixable = []
-
 # Exclude a variety of commonly ignored directories.
 exclude = [
     ".bzr",
@@ -207,27 +216,46 @@ exclude = [
 
 # Same as Black.
 line-length = 88
+indent-width = 4
+
+# Assume Python 3.8
+target-version = "py38"
+
+[tool.ruff.lint]
+# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
+select = ["E4", "E7", "E9", "F"]
+ignore = []
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
 
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
-# Assume Python 3.8
-target-version = "py38"
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+magic-trailing-comma = "respect"
 
-[tool.ruff.mccabe]
-# Unlike Flake8, default to a complexity level of 10.
-max-complexity = 10
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
 ```
 
 Some configuration options can be provided via the command-line, such as those related to
-rule enablement and disablement, file discovery, logging level, and more:
+rule enablement and disablement, file discovery, and logging level:
 
 ```shell
 ruff check path/to/code/ --select F401 --select F403 --quiet
 ```
 
-See `ruff help` for more on Ruff's top-level commands, or `ruff help check` for more on the
-linting command.
+See `ruff help` for more on Ruff's top-level commands, or `ruff help check` and `ruff help format`
+for more on the linting and formatting commands, respectively.
 
 ## Rules
 
@@ -238,7 +266,7 @@ isort, pyupgrade, and others. Regardless of the rule's origin, Ruff re-implement
 Rust as a first-party feature.
 
 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 just getting started with Ruff, **the default rule set is a great place to start**: it
@@ -330,7 +358,7 @@ In some cases, Ruff includes a "direct" Rust port of the corresponding tool.
 We're grateful to the maintainers of these tools for their work, and for all
 the value they've provided to the Python community.
 
-Ruff's autoformatter is built on a fork of Rome's [`rome_formatter`](https://github.com/rome/tools/tree/main/crates/rome_formatter),
+Ruff's formatter is built on a fork of Rome's [`rome_formatter`](https://github.com/rome/tools/tree/main/crates/rome_formatter),
 and again draws on both API and implementation details from [Rome](https://github.com/rome/tools),
 [Prettier](https://github.com/prettier/prettier), and [Black](https://github.com/psf/black).
 

diff --git a/crates/ruff_dev/src/generate_cli_help.rs b/crates/ruff_dev/src/generate_cli_help.rs
@@ -16,8 +16,11 @@ use crate::ROOT_DIR;
 const COMMAND_HELP_BEGIN_PRAGMA: &str = "<!-- Begin auto-generated command help. -->\n";
 const COMMAND_HELP_END_PRAGMA: &str = "<!-- End auto-generated command help. -->";
 
-const SUBCOMMAND_HELP_BEGIN_PRAGMA: &str = "<!-- Begin auto-generated subcommand help. -->\n";
-const SUBCOMMAND_HELP_END_PRAGMA: &str = "<!-- End auto-generated subcommand help. -->";
+const CHECK_HELP_BEGIN_PRAGMA: &str = "<!-- Begin auto-generated check help. -->\n";
+const CHECK_HELP_END_PRAGMA: &str = "<!-- End auto-generated check help. -->";
+
+const FORMAT_HELP_BEGIN_PRAGMA: &str = "<!-- Begin auto-generated format help. -->\n";
+const FORMAT_HELP_END_PRAGMA: &str = "<!-- End auto-generated format help. -->";
 
 #[derive(clap::Args)]
 pub(crate) struct Args {
@@ -56,11 +59,15 @@ pub(super) fn main(args: &Args) -> Result<()> {
     let command_help = trim_lines(&help_text());
 
     // Generate `ruff help check`.
-    let subcommand_help = trim_lines(&check_help_text());
+    let check_help = trim_lines(&subcommand_help_text("check")?);
+
+    // Generate `ruff help format`.
+    let format_help = trim_lines(&subcommand_help_text("format")?);
 
     if args.mode.is_dry_run() {
         print!("{command_help}");
-        print!("{subcommand_help}");
+        print!("{check_help}");
+        print!("{format_help}");
         return Ok(());
     }
 
@@ -77,9 +84,15 @@ pub(super) fn main(args: &Args) -> Result<()> {
     )?;
     let new = replace_docs_section(
         &new,
-        &format!("```text\n{subcommand_help}\n```\n\n"),
-        SUBCOMMAND_HELP_BEGIN_PRAGMA,
-        SUBCOMMAND_HELP_END_PRAGMA,
+        &format!("```text\n{check_help}\n```\n\n"),
+        CHECK_HELP_BEGIN_PRAGMA,
+        CHECK_HELP_END_PRAGMA,
+    )?;
+    let new = replace_docs_section(
+        &new,
+        &format!("```text\n{format_help}\n```\n\n"),
+        FORMAT_HELP_BEGIN_PRAGMA,
+        FORMAT_HELP_END_PRAGMA,
     )?;
 
     match args.mode {
@@ -104,18 +117,19 @@ fn help_text() -> String {
     args::Args::command().render_help().to_string()
 }
 
-/// Returns the output of `ruff help check`.
-fn check_help_text() -> String {
+/// Returns the output of a given subcommand (e.g., `ruff help check`).
+fn subcommand_help_text(subcommand: &str) -> Result<String> {
     let mut cmd = args::Args::command();
 
     // The build call is necessary for the help output to contain `Usage: ruff
     // check` instead of `Usage: check` see https://github.com/clap-rs/clap/issues/4685
     cmd.build();
 
-    cmd.find_subcommand_mut("check")
-        .expect("`check` subcommand not found")
+    Ok(cmd
+        .find_subcommand_mut(subcommand)
+        .with_context(|| format!("Unable to find subcommand `{subcommand}`"))?
         .render_help()
-        .to_string()
+        .to_string())
 }
 
 #[cfg(test)]

diff --git a/crates/ruff_linter/src/rules/flake8_implicit_str_concat/rules/implicit.rs b/crates/ruff_linter/src/rules/flake8_implicit_str_concat/rules/implicit.rs
@@ -20,7 +20,7 @@ use crate::settings::LinterSettings;
 /// negatively affects code readability.
 ///
 /// In some cases, the implicit concatenation may also be unintentional, as
-/// autoformatters are capable of introducing single-line implicit
+/// code formatters are capable of introducing single-line implicit
 /// concatenations when collapsing long lines.
 ///
 /// ## Example