From b25b6423717efa7a0197475253a421830850de15 Mon Sep 17 00:00:00 2001
From: Maddy Guthridge <miguelag2001@outlook.com>
Date: Tue, 27 May 2025 00:35:20 +1000
Subject: [PATCH] Improve readability of rule status icons in documentation
 (#18297)

Co-authored-by: Micha Reiser <micha@reiser.io>
---
 crates/ruff_dev/src/generate_rules_table.rs | 55 +++++++++------------
 1 file changed, 24 insertions(+), 31 deletions(-)

diff --git a/crates/ruff_dev/src/generate_rules_table.rs b/crates/ruff_dev/src/generate_rules_table.rs
index 73cdf65540..21b6aec0de 100644
--- a/crates/ruff_dev/src/generate_rules_table.rs
+++ b/crates/ruff_dev/src/generate_rules_table.rs
@@ -18,44 +18,43 @@ const FIX_SYMBOL: &str = "🛠️";
 const PREVIEW_SYMBOL: &str = "🧪";
 const REMOVED_SYMBOL: &str = "❌";
 const WARNING_SYMBOL: &str = "⚠️";
-const STABLE_SYMBOL: &str = "✔️";
 const SPACER: &str = "&nbsp;&nbsp;&nbsp;&nbsp;";
 
+/// Style for the rule's fixability and status icons.
+const SYMBOL_STYLE: &str = "style='width: 1em; display: inline-block;'";
+/// Style for the container wrapping the fixability and status icons.
+const SYMBOLS_CONTAINER: &str = "style='display: flex; gap: 0.5rem; justify-content: end;'";
+
 fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>, linter: &Linter) {
-    table_out.push_str("| Code | Name | Message | |");
+    table_out.push_str("| Code | Name | Message |    |");
     table_out.push('\n');
-    table_out.push_str("| ---- | ---- | ------- | ------: |");
+    table_out.push_str("| ---- | ---- | ------- | -: |");
     table_out.push('\n');
     for rule in rules {
         let status_token = match rule.group() {
             RuleGroup::Removed => {
-                format!("<span title='Rule has been removed'>{REMOVED_SYMBOL}</span>")
+                format!(
+                    "<span {SYMBOL_STYLE} title='Rule has been removed'>{REMOVED_SYMBOL}</span>"
+                )
             }
             RuleGroup::Deprecated => {
-                format!("<span title='Rule has been deprecated'>{WARNING_SYMBOL}</span>")
+                format!(
+                    "<span {SYMBOL_STYLE} title='Rule has been deprecated'>{WARNING_SYMBOL}</span>"
+                )
             }
             RuleGroup::Preview => {
-                format!("<span title='Rule is in preview'>{PREVIEW_SYMBOL}</span>")
-            }
-            RuleGroup::Stable => {
-                // A full opacity checkmark is a bit aggressive for indicating stable
-                format!("<span title='Rule is stable' style='opacity: 0.6'>{STABLE_SYMBOL}</span>")
+                format!("<span {SYMBOL_STYLE} title='Rule is in preview'>{PREVIEW_SYMBOL}</span>")
             }
+            RuleGroup::Stable => format!("<span {SYMBOL_STYLE}></span>"),
         };
 
         let fix_token = match rule.fixable() {
             FixAvailability::Always | FixAvailability::Sometimes => {
-                format!("<span title='Automatic fix available'>{FIX_SYMBOL}</span>")
-            }
-            FixAvailability::None => {
-                format!(
-                    "<span title='Automatic fix not available' style='opacity: 0.1' aria-hidden='true'>{FIX_SYMBOL}</span>"
-                )
+                format!("<span {SYMBOL_STYLE} title='Automatic fix available'>{FIX_SYMBOL}</span>")
             }
+            FixAvailability::None => format!("<span {SYMBOL_STYLE}></span>"),
         };
 
-        let tokens = format!("{status_token} {fix_token}");
-
         let rule_name = rule.as_ref();
 
         // If the message ends in a bracketed expression (like: "Use {replacement}"), escape the
@@ -82,15 +81,14 @@ fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>,
         #[expect(clippy::or_fun_call)]
         let _ = write!(
             table_out,
-            "| {ss}{0}{1}{se} {{ #{0}{1} }} | {ss}{2}{se} | {ss}{3}{se} | {ss}{4}{se} |",
-            linter.common_prefix(),
-            linter.code_for_rule(rule).unwrap(),
-            rule.explanation()
+            "| {ss}{prefix}{code}{se} {{ #{prefix}{code} }} | {ss}{explanation}{se} | {ss}{message}{se} | <div {SYMBOLS_CONTAINER}>{status_token}{fix_token}</div>|",
+            prefix = linter.common_prefix(),
+            code = linter.code_for_rule(rule).unwrap(),
+            explanation = rule
+                .explanation()
                 .is_some()
                 .then_some(format_args!("[{rule_name}](rules/{rule_name}.md)"))
                 .unwrap_or(format_args!("{rule_name}")),
-            message,
-            tokens,
         );
         table_out.push('\n');
     }
@@ -104,12 +102,6 @@ pub(crate) fn generate() -> String {
     table_out.push_str("### Legend");
     table_out.push('\n');
 
-    let _ = write!(
-        &mut table_out,
-        "{SPACER}{STABLE_SYMBOL}{SPACER} The rule is stable."
-    );
-    table_out.push_str("<br />");
-
     let _ = write!(
         &mut table_out,
         "{SPACER}{PREVIEW_SYMBOL}{SPACER} The rule is unstable and is in [\"preview\"](faq.md#what-is-preview)."
@@ -132,7 +124,8 @@ pub(crate) fn generate() -> String {
         &mut table_out,
         "{SPACER}{FIX_SYMBOL}{SPACER} The rule is automatically fixable by the `--fix` command-line option."
     );
-    table_out.push_str("<br />");
+    table_out.push_str("\n\n");
+    table_out.push_str("All rules not marked as preview, deprecated or removed are stable.");
     table_out.push('\n');
 
     for linter in Linter::iter() {