mirror of
https://github.com/astral-sh/ruff.git
synced 2026-11-21 12:16:15 +08:00
## Summary Use a shared ty override for Ruff’s standalone scripts now that PEP 723 scripts can inherit project settings. Fix the diagnostics in the two PR automation scripts so they can use the same checks. ## Notes to reviewers All 28 standalone scripts passed ty with locked dependencies, and the changed-file hooks and mocked workflow checks passed. --------- Co-authored-by: Alex Waygood <alex.waygood@gmail.com>
291 lines
9.9 KiB
Python
291 lines
9.9 KiB
Python
# /// script
|
|
# requires-python = ">=3.13"
|
|
# dependencies = [
|
|
# "mdformat>=1.0.0",
|
|
# "mdformat-mkdocs>=5.3.0",
|
|
# "pyyaml>=6.0.3",
|
|
# ]
|
|
#
|
|
# [tool.uv]
|
|
# no-build = true
|
|
# exclude-newer = "P7D"
|
|
# require-build-hashes = true
|
|
# preview-features = ["build-dependency-hashes", "missing-exclude-newer-package-lock"]
|
|
# ///
|
|
|
|
"""Generate an MkDocs-compatible `docs` and `mkdocs.yml` from the README.md."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import json
|
|
import re
|
|
import shutil
|
|
import subprocess
|
|
from collections.abc import Sequence
|
|
from pathlib import Path
|
|
from typing import NamedTuple
|
|
|
|
import mdformat
|
|
import yaml
|
|
|
|
|
|
class Section(NamedTuple):
|
|
"""A section to include in the MkDocs documentation."""
|
|
|
|
title: str
|
|
filename: str
|
|
generated: bool
|
|
# If subsections is present, the `filename` and `generated` value is unused.
|
|
subsections: Sequence[Section] | None = None
|
|
|
|
|
|
SECTIONS: list[Section] = [
|
|
Section("Overview", "index.md", generated=True),
|
|
Section("Tutorial", "tutorial.md", generated=False),
|
|
Section("Installing Ruff", "installation.md", generated=False),
|
|
Section("The Ruff Linter", "linter.md", generated=False),
|
|
Section("The Ruff Formatter", "formatter.md", generated=False),
|
|
Section(
|
|
"Editors",
|
|
"",
|
|
generated=False,
|
|
subsections=[
|
|
Section("Editor Integration", "editors/index.md", generated=False),
|
|
Section("Setup", "editors/setup.md", generated=False),
|
|
Section("Features", "editors/features.md", generated=False),
|
|
Section("Settings", "editors/settings.md", generated=False),
|
|
Section("Migrating from ruff-lsp", "editors/migration.md", generated=False),
|
|
],
|
|
),
|
|
Section("Configuring Ruff", "configuration.md", generated=False),
|
|
Section("Preview", "preview.md", generated=False),
|
|
Section("Rules", "rules.md", generated=True),
|
|
Section("Default Rules", "default-rules.md", generated=True),
|
|
Section("Settings", "settings.md", generated=True),
|
|
Section("Versioning", "versioning.md", generated=False),
|
|
Section("Integrations", "integrations.md", generated=False),
|
|
Section("FAQ", "faq.md", generated=False),
|
|
Section("Contributing", "contributing.md", generated=True),
|
|
Section("Proposing Lint Rules", "rule-proposals.md", generated=False),
|
|
]
|
|
|
|
LINK_REWRITES: dict[str, str] = {
|
|
"https://docs.astral.sh/ruff/": "index.md",
|
|
"https://docs.astral.sh/ruff/configuration/": "configuration.md",
|
|
"https://docs.astral.sh/ruff/configuration/#config-file-discovery": (
|
|
"configuration.md#config-file-discovery"
|
|
),
|
|
"https://docs.astral.sh/ruff/contributing/": "contributing.md",
|
|
"https://docs.astral.sh/ruff/editors": "editors/index.md",
|
|
"https://docs.astral.sh/ruff/editors/setup": "editors/setup.md",
|
|
"https://docs.astral.sh/ruff/faq/#how-does-ruffs-linter-compare-to-flake8": (
|
|
"faq.md#how-does-ruffs-linter-compare-to-flake8"
|
|
),
|
|
"https://docs.astral.sh/ruff/faq/#how-does-ruffs-import-sorting-compare-to-isort": (
|
|
"faq.md#how-does-ruffs-import-sorting-compare-to-isort"
|
|
),
|
|
"https://docs.astral.sh/ruff/faq/#how-does-ruffs-formatter-compare-to-black": (
|
|
"faq.md#how-does-ruffs-formatter-compare-to-black"
|
|
),
|
|
"https://docs.astral.sh/ruff/installation/": "installation.md",
|
|
"https://docs.astral.sh/ruff/rules/": "rules.md",
|
|
"https://docs.astral.sh/ruff/default-rules/": "default-rules.md",
|
|
"https://docs.astral.sh/ruff/settings/": "settings.md",
|
|
"https://docs.astral.sh/ruff/preview/": "preview.md",
|
|
}
|
|
|
|
|
|
def clean_file_content(content: str, title: str) -> str:
|
|
"""Add missing title, fix the header depth, and remove trailing empty lines."""
|
|
lines = content.splitlines()
|
|
if lines[0].startswith("# "):
|
|
return content
|
|
|
|
in_code_block = False
|
|
for i, line in enumerate(lines):
|
|
if line.startswith("```"):
|
|
in_code_block = not in_code_block
|
|
if not in_code_block and line.startswith("#"):
|
|
lines[i] = line[1:]
|
|
|
|
# Remove trailing empty lines.
|
|
for line in reversed(lines):
|
|
if line == "":
|
|
del lines[-1]
|
|
else:
|
|
break
|
|
|
|
content = "\n".join(lines) + "\n"
|
|
|
|
# Add a missing title.
|
|
return f"# {title}\n\n" + content
|
|
|
|
|
|
def generate_rule_metadata(rule_doc: Path) -> None:
|
|
"""Add frontmatter metadata containing a rule's description and optional code.
|
|
|
|
For example:
|
|
```yaml
|
|
---
|
|
description: Checks for abstract classes without abstract methods or properties.
|
|
tags:
|
|
- B024
|
|
---
|
|
```
|
|
"""
|
|
# Read the rule doc into lines.
|
|
with rule_doc.open("r", encoding="utf-8") as f:
|
|
lines = f.readlines()
|
|
|
|
# Get the description and rule code from the rule doc lines.
|
|
rule_code = None
|
|
description = None
|
|
title_found = False
|
|
what_it_does_found = False
|
|
for line in lines:
|
|
if line == "\n":
|
|
continue
|
|
|
|
# Assume that the only first-level heading is the rule title and optional code.
|
|
#
|
|
# For example: given `# abstract-base-class-without-abstract-method (B024)`,
|
|
# extract the rule code (`B024`).
|
|
if line.startswith("# "):
|
|
title_found = True
|
|
_, separator, code = line.strip().rpartition(" (")
|
|
if separator and code.endswith(")"):
|
|
rule_code = code[:-1]
|
|
|
|
if line.startswith("## What it does"):
|
|
what_it_does_found = True
|
|
continue # Skip the '## What it does' line
|
|
|
|
if what_it_does_found and description is None:
|
|
description = line.removesuffix("\n")
|
|
|
|
if title_found and description is not None:
|
|
break
|
|
else:
|
|
if not title_found:
|
|
raise ValueError("Missing title line")
|
|
|
|
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:
|
|
metadata = ["---", "description: |-", f" {description}"]
|
|
if rule_code is not None:
|
|
metadata.extend(["tags:", f"- {rule_code}"])
|
|
metadata.extend(["---", "", ""])
|
|
f.write("\n".join(metadata))
|
|
f.writelines(lines)
|
|
|
|
|
|
def main() -> None:
|
|
"""Generate an MkDocs-compatible `docs` and `mkdocs.yml`."""
|
|
subprocess.run(["cargo", "dev", "generate-docs"], check=True)
|
|
|
|
with Path("README.md").open(encoding="utf8") as fp:
|
|
content = fp.read()
|
|
|
|
# Rewrite links to the documentation.
|
|
for src, dst in LINK_REWRITES.items():
|
|
before = content
|
|
after = content.replace(f"({src})", f"({dst})")
|
|
if before == after:
|
|
msg = f"Unexpected link rewrite in README.md: {src}"
|
|
raise ValueError(msg)
|
|
content = after
|
|
|
|
if m := re.search(r"\(https://docs.astral.sh/ruff/.*\)", content):
|
|
msg = f"Unexpected absolute link to documentation: {m.group(0)}"
|
|
raise ValueError(msg)
|
|
|
|
Path("docs").mkdir(parents=True, exist_ok=True)
|
|
|
|
# Split the README.md into sections.
|
|
for title, filename, generated, _ in SECTIONS:
|
|
if not generated:
|
|
continue
|
|
|
|
with Path(f"docs/{filename}").open("w+", encoding="utf8") as f:
|
|
if filename == "contributing.md":
|
|
# Copy the CONTRIBUTING.md.
|
|
shutil.copy("CONTRIBUTING.md", "docs/contributing.md")
|
|
continue
|
|
|
|
if filename == "settings.md":
|
|
file_content = subprocess.check_output(
|
|
["cargo", "dev", "generate-options"],
|
|
encoding="utf-8",
|
|
)
|
|
elif filename == "default-rules.md":
|
|
file_content = subprocess.check_output(
|
|
["cargo", "dev", "generate-default-rules"],
|
|
encoding="utf-8",
|
|
)
|
|
else:
|
|
block = content.split(f"<!-- Begin section: {title} -->\n\n")
|
|
if len(block) != 2:
|
|
msg = f"Section {title} not found in README.md"
|
|
raise ValueError(msg)
|
|
|
|
block = block[1].split(f"\n<!-- End section: {title} -->")
|
|
if len(block) != 2:
|
|
msg = f"Section {title} not found in README.md"
|
|
raise ValueError(msg)
|
|
|
|
file_content = block[0]
|
|
|
|
if filename == "rules.md":
|
|
file_content += "\n" + subprocess.check_output(
|
|
["cargo", "dev", "generate-rules-table"],
|
|
encoding="utf-8",
|
|
)
|
|
|
|
f.write(clean_file_content(file_content, title))
|
|
|
|
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"])
|
|
|
|
generate_rule_metadata(rule_doc)
|
|
|
|
with Path("mkdocs.template.yml").open(encoding="utf8") as fp:
|
|
config = yaml.safe_load(fp)
|
|
|
|
# Add the redirect section to mkdocs.yml.
|
|
redirect_maps = json.loads(
|
|
subprocess.check_output(["cargo", "dev", "generate-rule-redirects"]),
|
|
)
|
|
config["plugins"].append({"redirects": {"redirect_maps": redirect_maps}})
|
|
|
|
# Add the nav section to mkdocs.yml.
|
|
config["nav"] = []
|
|
for section in SECTIONS:
|
|
if section.subsections is None:
|
|
config["nav"].append({section.title: section.filename})
|
|
else:
|
|
config["nav"].append(
|
|
{
|
|
section.title: [
|
|
{subsection.title: subsection.filename}
|
|
for subsection in section.subsections
|
|
]
|
|
}
|
|
)
|
|
|
|
with Path("mkdocs.generated.yml").open("w+", encoding="utf8") as fp:
|
|
yaml.safe_dump(config, fp)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
parser = argparse.ArgumentParser(
|
|
description="Generate an MkDocs-compatible `docs` and `mkdocs.yml`.",
|
|
)
|
|
args = parser.parse_args()
|
|
main()
|