From a98dbcee78bcee6dd1ef3fa3df8653427ae4145b Mon Sep 17 00:00:00 2001
From: Calum Young <32770960+calumy@users.noreply.github.com>
Date: Mon, 9 Sep 2024 15:01:59 +0100
Subject: [PATCH] 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        |  1 +
 scripts/generate_mkdocs.py | 34 +++++++++++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 359971d51e..9262bf046c 100644
--- a/mkdocs.template.yml
+++ b/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
diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py
index 6e24f9ec25..1e3c5ba521 100644
--- a/scripts/generate_mkdocs.py
+++ b/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)