Address review suggestions, update rule docs

astral-sh · AlexWaygood · Aug 14, 2024 · Aug 14, 2024 · Aug 14, 2024 · Aug 14, 2024
commit 0e05790a622da6c94392d4bef7869d7dbf3c7e2f
diff --git a/crates/ruff_linter/src/rules/flake8_bugbear/rules/useless_comparison.rs b/crates/ruff_linter/src/rules/flake8_bugbear/rules/useless_comparison.rs
@@ -10,6 +10,9 @@ use super::super::helpers::at_last_top_level_expression_in_cell;
 //togithub.com/ ## What it does
 //togithub.com/ Checks for useless comparisons.
 //togithub.com/
+//togithub.com/ For Jupyter Notebooks, this rule ignores to check the last top-level expression for each cell.
+//togithub.com/ This is because it's common to have a cell that ends with an expression to display it's value.
+//togithub.com/
 //togithub.com/ ## Why is this bad?
 //togithub.com/ Useless comparisons have no effect on the program, and are often included
 //togithub.com/ by mistake. If the comparison is intended to enforce an invariant, prepend
@@ -43,9 +46,6 @@ impl Violation for UselessComparison {
 //togithub.com/ B015
 pub(crate) fn useless_comparison(checker: &mut Checker, expr: &Expr) {
     if expr.is_compare_expr() {
-        // For Jupyter Notebooks, ignore the last top-level expression for each cell.
-        // This is because it's common to have a cell that ends with an expression
-        // to display it's value.
         if checker.source_type.is_ipynb()
             && at_last_top_level_expression_in_cell(
                 checker.semantic(),

diff --git a/crates/ruff_linter/src/rules/flake8_bugbear/rules/useless_expression.rs b/crates/ruff_linter/src/rules/flake8_bugbear/rules/useless_expression.rs
@@ -11,6 +11,9 @@ use super::super::helpers::at_last_top_level_expression_in_cell;
 //togithub.com/ ## What it does
 //togithub.com/ Checks for useless expressions.
 //togithub.com/
+//togithub.com/ For Jupyter Notebooks, this rule ignores to check the last top-level expression for each cell.
+//togithub.com/ This is because it's common to have a cell that ends with an expression to display it's value.
+//togithub.com/
 //togithub.com/ ## Why is this bad?
 //togithub.com/ Useless expressions have no effect on the program, and are often included
 //togithub.com/ by mistake. Assign a useless expression to a variable, or remove it
@@ -81,9 +84,6 @@ pub(crate) fn useless_expression(checker: &mut Checker, value: &Expr) {
         return;
     }
 
-    // For Jupyter Notebooks, ignore the last top-level expression for each cell.
-    // This is because it's common to have a cell that ends with an expression
-    // to display it's value.
     if checker.source_type.is_ipynb()
         && at_last_top_level_expression_in_cell(
             checker.semantic(),

diff --git a/crates/ruff_linter/src/rules/pycodestyle/rules/module_import_not_at_top_of_file.rs b/crates/ruff_linter/src/rules/pycodestyle/rules/module_import_not_at_top_of_file.rs
@@ -6,8 +6,9 @@ use ruff_text_size::Ranged;
 use crate::checkers::ast::Checker;
 
 //togithub.com/ ## What it does
-//togithub.com/ Checks for imports that are not at the top of the file. For Jupyter notebooks, this
-//togithub.com/ checks for imports that are not at the top of the cell.
+//togithub.com/ Checks for imports that are not at the top of the file.
+//togithub.com/
+//togithub.com/ For Jupyter notebooks, this checks for imports that are not at the top of the cell.
 //togithub.com/
 //togithub.com/ ## Why is this bad?
 //togithub.com/ According to [PEP 8], "imports are always put at the top of the file, just after any

diff --git a/crates/ruff_linter/src/rules/pydocstyle/rules/not_missing.rs b/crates/ruff_linter/src/rules/pydocstyle/rules/not_missing.rs
@@ -10,6 +10,8 @@ use ruff_text_size::TextRange;
 use crate::checkers::ast::Checker;
 use crate::registry::Rule;
 
+//togithub.com/ This rule is ignored for Jupyter Notebooks.
+//togithub.com/
 //togithub.com/ ## What it does
 //togithub.com/ Checks for undocumented public module definitions.
 //togithub.com/

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -367,9 +367,8 @@ You can also change the default selection using the [`include`](settings.md#incl
 Ruff has built-in support for linting and formatting [Jupyter Notebooks](https://jupyter.org/).
 
 !!! info
-    Notebooks are linted and formatted by default from Ruff version `0.6.0` onwards which marks
-    Jupyter Notebook support as stable. You can opt-out of linting and formatting notebooks by
-    adding `*.ipynb` to [`extend-exclude`](settings.md#extend-exclude).
+    Jupyter Notebook support is marked as stable from Ruff version `0.6.0` onwards and will
+    be linted and formatted by default.
 
 If you'd prefer to either only lint or only format Jupyter Notebook files, you can use the
 section specific `exclude` option to do so. For example, the following would only lint Jupyter
@@ -405,6 +404,45 @@ And, conversely, the following would only format Jupyter Notebook files and not
     exclude = ["*.ipynb"]
     ```
 
+You can completely disable Jupyter Notebook support by updating the
+[`extend-exclude`](settings.md#extend-exclude) settings:
+
+=== "pyproject.toml"
+
+    ```toml
+    [tool.ruff]
+    extend-exclude = ["*.ipynb"]
+    ```
+
+=== "ruff.toml"
+
+    ```toml
+    extend-exclude = ["*.ipynb"]
+    ```
+
+If you'd like to ignore certain rules specifically for Jupyter Notebook files, you can do so by
+using the [`per-file-ignores`](settings.md#per-file-ignores) setting:
+
+=== "pyproject.toml"
+
+    ```toml
+    [tool.ruff.lint.per-file-ignores]
+    "*.ipynb" = ["T20"]
+    ```
+
+=== "ruff.toml"
+
+    ```toml
+    [lint.per-file-ignores]
+    "*.ipynb" = ["T20"]
+    ```
+
+There are certain rules that has different behavior when applied to Jupyter Notebook files. For
+example, the [`module-import-not-at-top-of-file` (`E402`)](rules/module-import-not-at-top-of-file.md)
+rule works at the cell level where the rule is violated only if an import statement is not at the
+top of the **cell**. The rule documentation will specify if it has different behavior for Jupyter
+Notebook files.
+
 ## Command-line interface
 
 Some configuration options can be provided or overridden via dedicated flags on the command line.