Tweak format for rule explanations (#2645)

crates/ruff_cli/src/commands.rs

@@ -278,34 +278,36 @@ pub fn rule(rule: &Rule, format: HelpFormat) -> Result<()> {
     let mut stdout = BufWriter::new(io::stdout().lock());
     match format {
         HelpFormat::Text => {
-            writeln!(
+            let mut output = String::new();
-                stdout,
+            output.push_str(&format!("# {} ({})", rule.as_ref(), rule.code()));
-                "[{}] {} ({})",
+            output.push('\n');
-                linter.name(),
+            output.push('\n');
-                rule.as_ref(),
+
-                rule.code(),
+            let (linter, _) = Linter::parse_code(rule.code()).unwrap();
-            )?;
+            output.push_str(&format!("Derived from the **{}** linter.", linter.name()));
-            writeln!(stdout)?;
+            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');
+            }
+
             if let Some(explanation) = rule.explanation() {
-                writeln!(stdout, "{}", explanation.trim())?;
+                output.push_str(explanation.trim());
             } else {
-                writeln!(stdout, "Message formats:")?;
+                output.push_str("Message formats:");
                 for format in rule.message_formats() {
-                    writeln!(stdout, "* {format}")?;
+                    output.push('\n');
+                    output.push_str(&format!("* {}", format));
                 }
             }
 
-            if let Some(autofix) = rule.autofixable() {
+            writeln!(stdout, "{}", output)?;
-                writeln!(stdout)?;
-                writeln!(
-                    stdout,
-                    "{}",
-                    match autofix.available {
-                        AutofixAvailability::Sometimes => "Autofix is sometimes available.",
-                        AutofixAvailability::Always => "Autofix is always available.",
-                    }
-                )?;
-            }
         }
         HelpFormat::Json => {
             writeln!(

crates/ruff_dev/src/generate_docs.rs

@@ -4,9 +4,10 @@
 use std::fs;
 
 use anyhow::Result;
+use ruff::AutofixAvailability;
 use strum::IntoEnumIterator;
 
-use ruff::registry::Rule;
+use ruff::registry::{Linter, Rule, RuleNamespace};
 
 #[derive(clap::Args)]
 pub struct Args {
@@ -18,13 +19,29 @@ pub struct Args {
 pub fn main(args: &Args) -> Result<()> {
     for rule in Rule::iter() {
         if let Some(explanation) = rule.explanation() {
-            let explanation = format!("# {} ({})\n\n{}", rule.as_ref(), rule.code(), explanation);
+            let mut output = String::new();
+            output.push_str(&format!("# {} ({})", rule.as_ref(), rule.code()));
+            output.push('\n');
+
+            let (linter, _) = Linter::parse_code(rule.code()).unwrap();
+            output.push_str(&format!("Derived from the **{}** linter.", linter.name()));
+            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_str(explanation.trim());
 
             if args.dry_run {
-                println!("{}", explanation);
+                println!("{}", output);
             } else {
                 fs::create_dir_all("docs/rules")?;
-                fs::write(format!("docs/rules/{}.md", rule.as_ref()), explanation)?;
+                fs::write(format!("docs/rules/{}.md", rule.as_ref()), output)?;
             }
         }
     }

docs/rules/assert-raises-exception.md

@@ -1,13 +1,13 @@
 # assert-raises-exception (B017)
-
+Derived from the **flake8-bugbear** linter.
 ### What it does
-Checks for the use of `assertRaises(Exception)`.
+Checks for `self.assertRaises(Exception)`.
 
 ### Why is this bad?
 `assertRaises(Exception)` can lead to your test passing even if the
-code being tested is never executed (e.g., due to a typo).
+code being tested is never executed due to a typo.
 
-Assert for a more specific exception (builtin or custom), use
+Either assert for a more specific exception (builtin or custom), use
 `assertRaisesRegex` or the context manager form of `assertRaises`.
 
 ### Example
@@ -18,4 +18,4 @@ self.assertRaises(Exception, foo)
 Use instead:
 ```python
 self.assertRaises(SomeSpecificException, foo)
-```
+```