Create per-rule pages and link from README (#2644)

crates/ruff_dev/src/generate_all.rs

@@ -2,7 +2,9 @@
 
 use anyhow::Result;
 
-use crate::{generate_cli_help, generate_json_schema, generate_options, generate_rules_table};
+use crate::{
+    generate_cli_help, generate_docs, generate_json_schema, generate_options, generate_rules_table,
+};
 
 #[derive(clap::Args)]
 pub struct Args {
@@ -12,6 +14,9 @@ pub struct Args {
 }
 
 pub fn main(args: &Args) -> Result<()> {
+    generate_docs::main(&generate_docs::Args {
+        dry_run: args.dry_run,
+    })?;
     generate_json_schema::main(&generate_json_schema::Args {
         dry_run: args.dry_run,
     })?;

crates/ruff_dev/src/generate_docs.rs

@@ -1 +1,32 @@
+//! Generate Markdown documentation for applicable rules.
+#![allow(clippy::print_stdout, clippy::print_stderr)]
 
+use std::fs;
+
+use anyhow::Result;
+use strum::IntoEnumIterator;
+
+use ruff::registry::Rule;
+
+#[derive(clap::Args)]
+pub struct Args {
+    /// Write the generated docs to stdout (rather than to the filesystem).
+    #[arg(long)]
+    pub(crate) dry_run: bool,
+}
+
+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);
+
+            if args.dry_run {
+                println!("{}", explanation);
+            } else {
+                fs::create_dir_all("docs/rules")?;
+                fs::write(format!("docs/rules/{}.md", rule.as_ref()), explanation)?;
+            }
+        }
+    }
+    Ok(())
+}

crates/ruff_dev/src/generate_rules_table.rs

@@ -14,6 +14,8 @@ const TABLE_END_PRAGMA: &str = "<!-- End auto-generated sections. -->";
 const TOC_BEGIN_PRAGMA: &str = "<!-- Begin auto-generated table of contents. -->";
 const TOC_END_PRAGMA: &str = "<!-- End auto-generated table of contents. -->";
 
+const URL_PREFIX: &str = "https://github.com/charliermarsh/ruff/blob/main/docs/rules";
+
 #[derive(clap::Args)]
 pub struct Args {
     /// Write the generated table to stdout (rather than to `README.md`).
@@ -32,13 +34,27 @@ fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>)
             Some(_) => "🛠",
         };
 
-        table_out.push_str(&format!(
-            "| {} | {} | {} | {} |",
-            rule.code(),
-            rule.as_ref(),
-            rule.message_formats()[0].replace('|', r"\|"),
-            fix_token
-        ));
+        if rule.explanation().is_some() {
+            table_out.push_str(&format!(
+                "| [{}]({}/{}.md) | [{}]({}/{}.md) | {} | {} |",
+                rule.code(),
+                URL_PREFIX,
+                rule.as_ref(),
+                rule.as_ref(),
+                URL_PREFIX,
+                rule.as_ref(),
+                rule.message_formats()[0].replace('|', r"\|"),
+                fix_token
+            ));
+        } else {
+            table_out.push_str(&format!(
+                "| {} | {} | {} | {} |",
+                rule.code(),
+                rule.as_ref(),
+                rule.message_formats()[0].replace('|', r"\|"),
+                fix_token
+            ));
+        }
         table_out.push('\n');
     }
     table_out.push('\n');

crates/ruff_dev/src/main.rs

@@ -39,6 +39,8 @@ enum Command {
     GenerateOptions(generate_options::Args),
     /// Generate CLI help.
     GenerateCliHelp(generate_cli_help::Args),
+    /// Generate Markdown docs.
+    GenerateDocs(generate_docs::Args),
     /// Print the AST for a given Python file.
     PrintAST(print_ast::Args),
     /// Print the LibCST CST for a given Python file.
@@ -57,6 +59,7 @@ fn main() -> Result<()> {
         Command::GenerateRulesTable(args) => generate_rules_table::main(args)?,
         Command::GenerateOptions(args) => generate_options::main(args)?,
         Command::GenerateCliHelp(args) => generate_cli_help::main(args)?,
+        Command::GenerateDocs(args) => generate_docs::main(args)?,
         Command::PrintAST(args) => print_ast::main(args)?,
         Command::PrintCST(args) => print_cst::main(args)?,
         Command::PrintTokens(args) => print_tokens::main(args)?,