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)