#!/usr/bin/env python

"""

generate_ref_files.py

Create missing Markdown reference stubs for mkdocstrings.

Usage:

python scripts/generate_ref_files.py

"""

from pathlib import Path

# ---- Paths -----------------------------------------------------------

REPO_ROOT = Path(__file__).resolve().parent.parent.parent # adjust if layout differs

SRC_ROOT = REPO_ROOT / "src" / "agents" # source tree to scan

DOCS_ROOT = REPO_ROOT / "docs" / "ref" # where stubs go

# ---- Helpers ---------------------------------------------------------

def to_identifier(py_path: Path) -> str:

"""Convert src/agents/foo/bar.py -> 'agents.foo.bar'."""

rel = py_path.relative_to(SRC_ROOT).with_suffix("") # drop '.py'

return ".".join(("agents", *rel.parts))

def md_target(py_path: Path) -> Path:

"""Return docs/ref/.../*.md path corresponding to py_path."""

rel = py_path.relative_to(SRC_ROOT).with_suffix(".md")

return DOCS_ROOT / rel

def pretty_title(last_segment: str) -> str:

"""

Convert a module/file segment like 'tool_context' to 'Tool Context'.

Handles underscores and hyphens; leaves camelCase as‑is except first‑letter cap.

"""

cleaned = last_segment.replace("_", " ").replace("-", " ")

return cleaned.title()

# ---- Main ------------------------------------------------------------

def main() -> None:

if not SRC_ROOT.exists():

raise SystemExit(f"Source path not found: {SRC_ROOT}")

created = 0

for py_file in SRC_ROOT.rglob("*.py"):

if py_file.name.startswith("_"): # skip private files

continue

md_path = md_target(py_file)

if md_path.exists():

continue # keep existing

md_path.parent.mkdir(parents=True, exist_ok=True)

identifier = to_identifier(py_file)

title = pretty_title(identifier.split(".")[-1]) # last segment

md_content = f"""# `{title}`

::: {identifier}

"""

md_path.write_text(md_content, encoding="utf-8")

created += 1

print(f"Created {md_path.relative_to(REPO_ROOT)}")

if created == 0:

print("All reference files were already present.")

else:

print(f"Done. {created} new file(s) created.")

if __name__ == "__main__":

main()