Add meta descriptions to rule pages (#13234)

## Summary

This PR updates the `scripts/generate_mkdocs.py` to add meta
descriptions to each rule as well as a fallback `site_description`.

I was initially planning to add this to `generate_docs.rs`; however
running `mdformat` on the rules caused the format of the additional
description to change into a state that mkdocs could not handle.

Fixes #13197 

## Test Plan

- Run  `python scripts/generate_mkdocs.py` to build the documentation
- Run `mkdocs serve -f mkdocs.public.yml` to serve the docs site locally
- Navigate to a rule on both the local site and the current production
site and note the addition of the description head tag. For example:
  - http://127.0.0.1:8000/ruff/rules/unused-import/

![image](https://github.com/user-attachments/assets/f47ae4fa-fe5b-42e1-8874-cb36a2ef2c9b)
  - https://docs.astral.sh/ruff/rules/unused-import/

![image](https://github.com/user-attachments/assets/6a650bff-2fcb-4df2-9cb6-40f66a2a5b8a)

mkdocs.template.yml

@@ -37,6 +37,7 @@ repo_name: ruff
 site_author: charliermarsh
 site_url: https://docs.astral.sh/ruff/
 site_dir: site/ruff
+site_description: An extremely fast Python linter and code formatter, written in Rust.
 markdown_extensions:
   - admonition
   - pymdownx.details

scripts/generate_mkdocs.py

@@ -104,6 +104,34 @@ def clean_file_content(content: str, title: str) -> str:
     return f"# {title}\n\n" + content
 
 
+def add_meta_description(rule_doc: Path) -> str:
+    """Add a meta description to the rule doc."""
+    # Read the rule doc into lines
+    with rule_doc.open("r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    # Get the description from the rule doc lines
+    what_it_does_found = False
+    for line in lines:
+        if line == "\n":
+            continue
+
+        if line.startswith("## What it does"):
+            what_it_does_found = True
+            continue  # Skip the '## What it does' line
+
+        if what_it_does_found:
+            description = line.removesuffix("\n")
+            break
+    else:
+        if not what_it_does_found:
+            raise ValueError(f"Missing '## What it does' in {rule_doc}")
+
+    with rule_doc.open("w", encoding="utf-8") as f:
+        f.writelines("\n".join(["---", f"description: {description}", "---", "", ""]))
+        f.writelines(lines)
+
+
 def main() -> None:
     """Generate an MkDocs-compatible `docs` and `mkdocs.yml`."""
     subprocess.run(["cargo", "dev", "generate-docs"], check=True)
@@ -163,11 +191,15 @@ def main() -> None:
 
             f.write(clean_file_content(file_content, title))
 
-    # Format rules docs
     add_no_escape_text_plugin()
     for rule_doc in Path("docs/rules").glob("*.md"):
+        # Format rules docs. This has to be completed before adding the meta description
+        # otherwise the meta description will be formatted in a way that mkdocs does not
+        # support.
         mdformat.file(rule_doc, extensions=["mkdocs", "admon", "no-escape-text"])
 
+        add_meta_description(rule_doc)
+
     with Path("mkdocs.template.yml").open(encoding="utf8") as fp:
         config = yaml.safe_load(fp)