"""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 itertools import chain

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("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),

]

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-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/settings/": "settings.md",

"#whos-using-ruff": "https://github.com/astral-sh/ruff#whos-using-ruff",

"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 code and description.

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

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 code.

#

# For example: given `# abstract-base-class-without-abstract-method (B024)`,

# extract the rule code (`B024`).

if line.startswith("# "):

rule_code = line.strip().rsplit("(", 1)

rule_code = rule_code[1][:-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 not description:

description = line.removesuffix("\n")

if all([rule_code, description]):

break

else:

if not rule_code:

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:

f.writelines(

"\n".join(

[

"---",

"description: |-",

f" {description}",

"tags:",

f"- {rule_code}",

"---",

"",

"",

]

)

)

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",

)

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.

rules = json.loads(

subprocess.check_output(

[

"cargo",

"run",

"-p",

"ruff",

"--",

"rule",

"--all",

"--output-format",

"json",

],

),

)

config["plugins"].append(

{

"redirects": {

"redirect_maps": dict(

chain.from_iterable(

[

(f"rules/{rule['code']}.md", f"rules/{rule['name']}.md"),

(

f"rules/{rule['code'].lower()}.md",

f"rules/{rule['name']}.md",

),

]

for rule in rules

)

),

},

},

)

# 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()