From abb34828bdbce0eff28d4350b8f188436e57be78 Mon Sep 17 00:00:00 2001 From: Matt Norton Date: Sun, 17 Nov 2024 09:16:47 +0000 Subject: [PATCH] Improve rule & options documentation (#14329) Co-authored-by: Charlie Marsh Co-authored-by: Micha Reiser --- .../rules/hardcoded_tmp_directory.rs | 1 + .../flake8_commas/rules/trailing_commas.rs | 12 +++++++++ .../rules/implicit.rs | 27 +++++++++++++++++++ .../rules/logical_lines/indentation.rs | 6 ++++- .../src/rules/pydocstyle/rules/sections.rs | 12 ++++----- crates/ruff_workspace/src/options.rs | 6 ++--- ruff.schema.json | 6 ++--- 7 files changed, 57 insertions(+), 13 deletions(-) diff --git a/crates/ruff_linter/src/rules/flake8_bandit/rules/hardcoded_tmp_directory.rs b/crates/ruff_linter/src/rules/flake8_bandit/rules/hardcoded_tmp_directory.rs index ba029f0e56..b57ad8d395 100644 --- a/crates/ruff_linter/src/rules/flake8_bandit/rules/hardcoded_tmp_directory.rs +++ b/crates/ruff_linter/src/rules/flake8_bandit/rules/hardcoded_tmp_directory.rs @@ -33,6 +33,7 @@ use crate::checkers::ast::Checker; /// /// ## Options /// - `lint.flake8-bandit.hardcoded-tmp-directory` +/// - `lint.flake8-bandit.hardcoded-tmp-directory-extend` /// /// ## References /// - [Common Weakness Enumeration: CWE-377](https://cwe.mitre.org/data/definitions/377.html) diff --git a/crates/ruff_linter/src/rules/flake8_commas/rules/trailing_commas.rs b/crates/ruff_linter/src/rules/flake8_commas/rules/trailing_commas.rs index e45053e188..be73f48ede 100644 --- a/crates/ruff_linter/src/rules/flake8_commas/rules/trailing_commas.rs +++ b/crates/ruff_linter/src/rules/flake8_commas/rules/trailing_commas.rs @@ -139,6 +139,12 @@ impl Context { /// "baz": 2, /// } /// ``` +/// +/// ## Formatter compatibility +/// We recommend against using this rule alongside the [formatter]. The +/// formatter enforces consistent use of trailing commas, making the rule redundant. +/// +/// [formatter]:https://docs.astral.sh/ruff/formatter/ #[violation] pub struct MissingTrailingComma; @@ -210,6 +216,12 @@ impl Violation for TrailingCommaOnBareTuple { /// ```python /// foo = (1, 2, 3) /// ``` +/// +/// ## Formatter compatibility +/// We recommend against using this rule alongside the [formatter]. The +/// formatter enforces consistent use of trailing commas, making the rule redundant. +/// +/// [formatter]:https://docs.astral.sh/ruff/formatter/ #[violation] pub struct ProhibitedTrailingComma; 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 index 7305c2cae5..c2b34f66c2 100644 --- 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 @@ -34,6 +34,20 @@ use crate::Locator; /// ```python /// z = "The quick brown fox." /// ``` +/// +/// # Formatter compatibility +/// Use of this rule alongside the [formatter] must be handled with care. +/// Currently, the [formatter] can introduce new single-line implicitly +/// concatenated strings, therefore we suggest rerunning the linter and +/// [formatter] in the following order: +/// 1. Run the linter with this rule (`ISC001`) disabled +/// 2. Run the [formatter] +/// 3. Rerun the linter with this rule (`ISC001`) enabled +/// This is one of very few cases where the [formatter] can produce code that +/// contains lint violations. It is a known issue that should be resolved by the +/// new 2025 style guide. +/// +/// [formatter]:https://docs.astral.sh/ruff/formatter/ #[violation] pub struct SingleLineImplicitStringConcatenation; @@ -81,7 +95,20 @@ impl Violation for SingleLineImplicitStringConcatenation { /// ## Options /// - `lint.flake8-implicit-str-concat.allow-multiline` /// +/// # Formatter compatibility +/// Use of this rule alongside the [formatter] must be handled with care. +/// Currently, the [formatter] can introduce new multi-line implicitly +/// concatenated strings, therefore we suggest rerunning the linter and +/// [formatter] in the following order: +/// 1. Run the linter with this rule (`ISC002`) disabled +/// 2. Run the [formatter] +/// 3. Rerun the linter with this rule (`ISC002`) enabled +/// This is one of very few cases where the [formatter] can produce code that +/// contains lint violations. It is a known issue that should be resolved by the +/// new 2025 style guide. +/// /// [PEP 8]: https://peps.python.org/pep-0008/#maximum-line-length +/// [formatter]:https://docs.astral.sh/ruff/formatter/ #[violation] pub struct MultiLineImplicitStringConcatenation; diff --git a/crates/ruff_linter/src/rules/pycodestyle/rules/logical_lines/indentation.rs b/crates/ruff_linter/src/rules/pycodestyle/rules/logical_lines/indentation.rs index 27e9719ede..a46a386a96 100644 --- a/crates/ruff_linter/src/rules/pycodestyle/rules/logical_lines/indentation.rs +++ b/crates/ruff_linter/src/rules/pycodestyle/rules/logical_lines/indentation.rs @@ -23,7 +23,6 @@ use super::LogicalLine; /// a = 1 /// ``` /// -/// /// ## Formatter compatibility /// We recommend against using this rule alongside the [formatter]. The /// formatter enforces consistent indentation, making the rule redundant. @@ -232,7 +231,12 @@ impl Violation for UnexpectedIndentationComment { /// pass /// ``` /// +/// ## Formatter compatibility +/// We recommend against using this rule alongside the [formatter]. The +/// formatter enforces consistent indentation, making the rule redundant. +/// /// [PEP 8]: https://peps.python.org/pep-0008/#indentation +/// [formatter]:https://docs.astral.sh/ruff/formatter/ #[violation] pub struct OverIndented { is_comment: bool, diff --git a/crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs b/crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs index f34dba528d..52b89de956 100644 --- a/crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs +++ b/crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs @@ -36,6 +36,9 @@ use crate::rules::pydocstyle::settings::Convention; /// indentation of the docstring's opening quotes, and the body should be /// indented one level further. /// +/// This rule is enabled when using the `numpy` and `google` conventions, and +/// disabled when using the `pep257` convention. +/// /// ## Example /// ```python /// def calculate_speed(distance: float, time: float) -> float: @@ -219,6 +222,9 @@ impl AlwaysFixableViolation for SectionUnderlineNotOverIndented { /// a blank line, followed by a series of sections. Each section typically has /// a header and a body. /// +/// This rule is enabled when using the `numpy` and `google` conventions, and +/// disabled when using the `pep257` convention. +/// /// ## Example /// ```python /// def calculate_speed(distance: float, time: float) -> float: @@ -1049,9 +1055,6 @@ impl AlwaysFixableViolation for BlankLineAfterLastSection { /// raise FasterThanLightError from exc /// ``` /// -/// ## Options -/// - `lint.pydocstyle.convention` -/// /// ## References /// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/) /// - [PEP 287 – reStructuredText Docstring Format](https://peps.python.org/pep-0287/) @@ -1294,9 +1297,6 @@ impl Violation for UndocumentedParam { /// raise FasterThanLightError from exc /// ``` /// -/// ## Options -/// - `lint.pydocstyle.convention` -/// /// ## References /// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/) /// - [PEP 287 – reStructuredText Docstring Format](https://peps.python.org/pep-0287/) diff --git a/crates/ruff_workspace/src/options.rs b/crates/ruff_workspace/src/options.rs index 7d9cdbfced..1bc15d0d6a 100644 --- a/crates/ruff_workspace/src/options.rs +++ b/crates/ruff_workspace/src/options.rs @@ -1007,7 +1007,7 @@ impl Flake8AnnotationsOptions { #[serde(deny_unknown_fields, rename_all = "kebab-case")] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] pub struct Flake8BanditOptions { - /// A list of directories to consider temporary. + /// A list of directories to consider temporary (see `S108`). #[option( default = "[\"/tmp\", \"/var/tmp\", \"/dev/shm\"]", value_type = "list[str]", @@ -1016,7 +1016,7 @@ pub struct Flake8BanditOptions { pub hardcoded_tmp_directory: Option>, /// A list of directories to consider temporary, in addition to those - /// specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory). + /// specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory) (see `S108`). #[option( default = "[]", value_type = "list[str]", @@ -2099,7 +2099,7 @@ pub struct IsortOptions { /// Use `-1` for automatic determination. /// /// Ruff uses at most one blank line after imports in typing stub files (files with `.pyi` extension) in accordance to - /// the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/source/stubs.html#blank-lines)). + /// the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#blank-lines)). /// /// When using the formatter, only the values `-1`, `1`, and `2` are compatible because /// it enforces at least one empty and at most two empty lines after imports. diff --git a/ruff.schema.json b/ruff.schema.json index 83f02006c7..42a7d8144a 100644 --- a/ruff.schema.json +++ b/ruff.schema.json @@ -948,7 +948,7 @@ ] }, "hardcoded-tmp-directory": { - "description": "A list of directories to consider temporary.", + "description": "A list of directories to consider temporary (see `S108`).", "type": [ "array", "null" @@ -958,7 +958,7 @@ } }, "hardcoded-tmp-directory-extend": { - "description": "A list of directories to consider temporary, in addition to those specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory).", + "description": "A list of directories to consider temporary, in addition to those specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory) (see `S108`).", "type": [ "array", "null" @@ -1700,7 +1700,7 @@ ] }, "lines-after-imports": { - "description": "The number of blank lines to place after imports. Use `-1` for automatic determination.\n\nRuff uses at most one blank line after imports in typing stub files (files with `.pyi` extension) in accordance to the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/source/stubs.html#blank-lines)).\n\nWhen using the formatter, only the values `-1`, `1`, and `2` are compatible because it enforces at least one empty and at most two empty lines after imports.", + "description": "The number of blank lines to place after imports. Use `-1` for automatic determination.\n\nRuff uses at most one blank line after imports in typing stub files (files with `.pyi` extension) in accordance to the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#blank-lines)).\n\nWhen using the formatter, only the values `-1`, `1`, and `2` are compatible because it enforces at least one empty and at most two empty lines after imports.", "type": [ "integer", "null"