Add documentation for flake8-quotes rules (#2650)

README.md

@@ -1162,10 +1162,10 @@ For more, see [flake8-quotes](https://pypi.org/project/flake8-quotes/) on PyPI.
 
 | Code | Name | Message | Fix |
 | ---- | ---- | ------- | --- |
-| Q000 | bad-quotes-inline-string | Double quotes found but single quotes preferred | 🛠 |
-| Q001 | bad-quotes-multiline-string | Double quote multiline found but single quotes preferred | 🛠 |
-| Q002 | bad-quotes-docstring | Double quote docstring found but single quotes preferred | 🛠 |
-| Q003 | avoid-quote-escape | Change outer quotes to avoid escaping inner quotes | 🛠 |
+| [Q000](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-inline-string.md) | [bad-quotes-inline-string](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-inline-string.md) | Double quotes found but single quotes preferred | 🛠 |
+| [Q001](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-multiline-string.md) | [bad-quotes-multiline-string](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-multiline-string.md) | Double quote multiline found but single quotes preferred | 🛠 |
+| [Q002](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-docstring.md) | [bad-quotes-docstring](https://github.com/charliermarsh/ruff/blob/main/docs/rules/bad-quotes-docstring.md) | Double quote docstring found but single quotes preferred | 🛠 |
+| [Q003](https://github.com/charliermarsh/ruff/blob/main/docs/rules/avoid-quote-escape.md) | [avoid-quote-escape](https://github.com/charliermarsh/ruff/blob/main/docs/rules/avoid-quote-escape.md) | Change outer quotes to avoid escaping inner quotes | 🛠 |
 
 ### flake8-return (RET)
 

crates/ruff/src/rules/flake8_quotes/rules.rs

@@ -12,6 +12,24 @@ use crate::source_code::Locator;
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
+    /// ### What it does
+    /// Checks for inline strings that use single quotes or double quotes,
+    /// depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes)
+    /// setting.
+    ///
+    /// ### Why is this bad?
+    /// Consistency is good. Use either single or double quotes for inline
+    /// strings, but be consistent.
+    ///
+    /// ### Example
+    /// ```python
+    /// foo = 'bar'
+    /// ```
+    ///
+    /// Assuming `inline-quotes` is set to `double`, use instead:
+    /// ```python
+    /// foo = "bar"
+    /// ```
     pub struct BadQuotesInlineString {
         pub quote: Quote,
     }
@@ -36,6 +54,28 @@ impl AlwaysAutofixableViolation for BadQuotesInlineString {
 }
 
 define_violation!(
+    /// ### What it does
+    /// Checks for multiline strings that use single quotes or double quotes,
+    /// depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes)
+    /// setting.
+    ///
+    /// ### Why is this bad?
+    /// Consistency is good. Use either single or double quotes for multiline
+    /// strings, but be consistent.
+    ///
+    /// ### Example
+    /// ```python
+    /// foo = '''
+    /// bar
+    /// '''
+    /// ```
+    ///
+    /// Assuming `multiline-quotes` is set to `double`, use instead:
+    /// ```python
+    /// foo = """
+    /// bar
+    /// """
+    /// ```
     pub struct BadQuotesMultilineString {
         pub quote: Quote,
     }
@@ -60,6 +100,27 @@ impl AlwaysAutofixableViolation for BadQuotesMultilineString {
 }
 
 define_violation!(
+    /// ### What it does
+    /// Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes)
+    /// setting.
+    ///
+    /// ### Why is this bad?
+    /// Consistency is good. Use either single or double quotes for docstring
+    /// strings, but be consistent.
+    ///
+    /// ### Example
+    /// ```python
+    /// '''
+    /// bar
+    /// '''
+    /// ```
+    ///
+    /// Assuming `docstring-quotes` is set to `double`, use instead:
+    /// ```python
+    /// """
+    /// bar
+    /// """
+    /// ```
     pub struct BadQuotesDocstring {
         pub quote: Quote,
     }
@@ -84,6 +145,23 @@ impl AlwaysAutofixableViolation for BadQuotesDocstring {
 }
 
 define_violation!(
+    /// ### What it does
+    /// Checks for strings that include escaped quotes, and suggests changing
+    /// the quote style to avoid the need to escape them.
+    ///
+    /// ### Why is this bad?
+    /// It's preferable to avoid escaped quotes in strings. By changing the
+    /// outer quote style, you can avoid escaping inner quotes.
+    ///
+    /// ### Example
+    /// ```python
+    /// foo = 'bar\'s'
+    /// ```
+    ///
+    /// Use instead:
+    /// ```python
+    /// foo = "bar's"
+    /// ```
     pub struct AvoidQuoteEscape;
 );
 impl AlwaysAutofixableViolation for AvoidQuoteEscape {

crates/ruff/src/rules/pylint/rules/comparison_of_constant.rs

@@ -1,11 +1,11 @@
 use std::fmt;
 
-use crate::ast::helpers::unparse_constant;
 use itertools::Itertools;
 use ruff_macros::{define_violation, derive_message_formats};
 use rustpython_parser::ast::{Cmpop, Expr, ExprKind, Located};
 use serde::{Deserialize, Serialize};
 
+use crate::ast::helpers::unparse_constant;
 use crate::ast::types::Range;
 use crate::checkers::ast::Checker;
 use crate::registry::Diagnostic;

crates/ruff/src/rules/pylint/rules/magic_value_comparison.rs

@@ -1,8 +1,8 @@
-use crate::ast::helpers::unparse_constant;
 use itertools::Itertools;
 use ruff_macros::{define_violation, derive_message_formats};
 use rustpython_parser::ast::{Constant, Expr, ExprKind};
 
+use crate::ast::helpers::unparse_constant;
 use crate::ast::types::Range;
 use crate::checkers::ast::Checker;
 use crate::registry::Diagnostic;

crates/ruff_dev/src/generate_docs.rs

@@ -4,11 +4,10 @@
 use std::fs;
 
 use anyhow::Result;
+use ruff::registry::{Linter, Rule, RuleNamespace};
 use ruff::AutofixAvailability;
 use strum::IntoEnumIterator;
 
-use ruff::registry::{Linter, Rule, RuleNamespace};
-
 #[derive(clap::Args)]
 pub struct Args {
     /// Write the generated docs to stdout (rather than to the filesystem).
@@ -22,17 +21,20 @@ pub fn main(args: &Args) -> Result<()> {
             let mut output = String::new();
             output.push_str(&format!("# {} ({})", rule.as_ref(), rule.code()));
             output.push('\n');
+            output.push('\n');
 
             let (linter, _) = Linter::parse_code(rule.code()).unwrap();
             output.push_str(&format!("Derived from the **{}** linter.", linter.name()));
             output.push('\n');
+            output.push('\n');
 
             if let Some(autofix) = rule.autofixable() {
                 output.push_str(match autofix.available {
                     AutofixAvailability::Sometimes => "Autofix is sometimes available.",
                     AutofixAvailability::Always => "Autofix is always available.",
                 });
                 output.push('\n');
+                output.push('\n');
             }
 
             output.push_str(explanation.trim());

docs/rules/assert-raises-exception.md

@@ -1,5 +1,7 @@
 # assert-raises-exception (B017)
+
 Derived from the **flake8-bugbear** linter.
+
 ### What it does
 Checks for `self.assertRaises(Exception)`.
 

docs/rules/avoid-quote-escape.md

@@ -0,0 +1,23 @@
+# avoid-quote-escape (Q003)
+
+Derived from the **flake8-quotes** linter.
+
+Autofix is always available.
+
+### What it does
+Checks for strings that include escaped quotes, and suggests changing
+the quote style to avoid the need to escape them.
+
+### Why is this bad?
+It's preferable to avoid escaped quotes in strings. By changing the
+outer quote style, you can avoid escaping inner quotes.
+
+### Example
+```python
+foo = 'bar\'s'
+```
+
+Use instead:
+```python
+foo = "bar's"
+```

docs/rules/bad-quotes-docstring.md

@@ -0,0 +1,27 @@
+# bad-quotes-docstring (Q002)
+
+Derived from the **flake8-quotes** linter.
+
+Autofix is always available.
+
+### What it does
+Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes)
+setting.
+
+### Why is this bad?
+Consistency is good. Use either single or double quotes for docstring
+strings, but be consistent.
+
+### Example
+```python
+'''
+bar
+'''
+```
+
+Assuming `docstring-quotes` is set to `double`, use instead:
+```python
+"""
+bar
+"""
+```

docs/rules/bad-quotes-inline-string.md

@@ -0,0 +1,24 @@
+# bad-quotes-inline-string (Q000)
+
+Derived from the **flake8-quotes** linter.
+
+Autofix is always available.
+
+### What it does
+Checks for inline strings that use single quotes or double quotes,
+depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes)
+setting.
+
+### Why is this bad?
+Consistency is good. Use either single or double quotes for inline
+strings, but be consistent.
+
+### Example
+```python
+foo = 'bar'
+```
+
+Assuming `inline-quotes` is set to `double`, use instead:
+```python
+foo = "bar"
+```

docs/rules/bad-quotes-multiline-string.md

@@ -0,0 +1,28 @@
+# bad-quotes-multiline-string (Q001)
+
+Derived from the **flake8-quotes** linter.
+
+Autofix is always available.
+
+### What it does
+Checks for multiline strings that use single quotes or double quotes,
+depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes)
+setting.
+
+### Why is this bad?
+Consistency is good. Use either single or double quotes for multiline
+strings, but be consistent.
+
+### Example
+```python
+foo = '''
+bar
+'''
+```
+
+Assuming `multiline-quotes` is set to `double`, use instead:
+```python
+foo = """
+bar
+"""
+```