Python
/
ruff
mirror of https://github.com/astral-sh/ruff
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve readability of rule status icons in documentation (#18297) 

Co-authored-by: Micha Reiser <micha@reiser.io>
This commit is contained in:
Maddy Guthridge 2025-05-27 00:35:20 +10:00 committed by GitHub
parent 175402aa75
commit b25b642371
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 24 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
crates/ruff_dev/src/generate_rules_table.rs
View File

@ -18,44 +18,43 @@ const FIX_SYMBOL: &str = "🛠️";
const PREVIEW_SYMBOL: &str = "🧪"; const PREVIEW_SYMBOL: &str = "🧪";
const REMOVED_SYMBOL: &str = "❌"; const REMOVED_SYMBOL: &str = "❌";
const WARNING_SYMBOL: &str = "⚠️"; const WARNING_SYMBOL: &str = "⚠️";
const STABLE_SYMBOL: &str = "✔️";
const SPACER: &str = "&nbsp;&nbsp;&nbsp;&nbsp;"; 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) { 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('\n');
table_out.push_str("| ---- | ---- | ------- | ------: |"); table_out.push_str("| ---- | ---- | ------- | -: |");
table_out.push('\n'); table_out.push('\n');
for rule in rules { for rule in rules {
let status_token = match rule.group() { let status_token = match rule.group() {
RuleGroup::Removed => { 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 => { 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 => { RuleGroup::Preview => {
format!("<span title='Rule is in preview'>{PREVIEW_SYMBOL}</span>") format!("<span {SYMBOL_STYLE} 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>")
} }
RuleGroup::Stable => format!("<span {SYMBOL_STYLE}></span>"),
}; };
let fix_token = match rule.fixable() { let fix_token = match rule.fixable() {
FixAvailability::Always | FixAvailability::Sometimes => { FixAvailability::Always | FixAvailability::Sometimes => {
format!("<span title='Automatic fix available'>{FIX_SYMBOL}</span>") format!("<span {SYMBOL_STYLE} 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>"
)
} }
FixAvailability::None => format!("<span {SYMBOL_STYLE}></span>"),
}; };
let tokens = format!("{status_token} {fix_token}");
let rule_name = rule.as_ref(); let rule_name = rule.as_ref();
// If the message ends in a bracketed expression (like: "Use {replacement}"), escape the // 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)] #[expect(clippy::or_fun_call)]
let _ = write!( let _ = write!(
table_out, table_out,
"| {ss}{0}{1}{se} {{ #{0}{1} }} | {ss}{2}{se} | {ss}{3}{se} | {ss}{4}{se} |", "| {ss}{prefix}{code}{se} {{ #{prefix}{code} }} | {ss}{explanation}{se} | {ss}{message}{se} | <div {SYMBOLS_CONTAINER}>{status_token}{fix_token}</div>|",
linter.common_prefix(), prefix = linter.common_prefix(),
linter.code_for_rule(rule).unwrap(), code = linter.code_for_rule(rule).unwrap(),
rule.explanation() explanation = rule
.explanation()
.is_some() .is_some()
.then_some(format_args!("[{rule_name}](rules/{rule_name}.md)")) .then_some(format_args!("[{rule_name}](rules/{rule_name}.md)"))
.unwrap_or(format_args!("{rule_name}")), .unwrap_or(format_args!("{rule_name}")),
message,
tokens,
); );
table_out.push('\n'); table_out.push('\n');
} }
@ -104,12 +102,6 @@ pub(crate) fn generate() -> String {
table_out.push_str("### Legend"); table_out.push_str("### Legend");
table_out.push('\n'); table_out.push('\n');
let _ = write!(
&mut table_out,
"{SPACER}{STABLE_SYMBOL}{SPACER} The rule is stable."
);
table_out.push_str("<br />");
let _ = write!( let _ = write!(
&mut table_out, &mut table_out,
"{SPACER}{PREVIEW_SYMBOL}{SPACER} The rule is unstable and is in [\"preview\"](faq.md#what-is-preview)." "{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, &mut table_out,
"{SPACER}{FIX_SYMBOL}{SPACER} The rule is automatically fixable by the `--fix` command-line option." "{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'); table_out.push('\n');
for linter in Linter::iter() { for linter in Linter::iter() {