Add automation script to generate mkdocstrings files

Makefile

@@ -44,6 +44,7 @@ old_version_tests:
 
 .PHONY: build-docs
 build-docs:
+	uv run docs/scripts/generate_ref_files.py
 	uv run mkdocs build
 
 .PHONY: build-full-docs

docs/ref/computer.md

@@ -0,0 +1,3 @@
+# `Computer`
+
+::: agents.computer

docs/ref/extensions/models/litellm_model.md

@@ -0,0 +1,3 @@
+# `LiteLLM Model`
+
+::: agents.extensions.models.litellm_model

docs/ref/extensions/models/litellm_provider.md

@@ -0,0 +1,3 @@
+# `LiteLLM Provider`
+
+::: agents.extensions.models.litellm_provider

docs/ref/extensions/visualization.md

@@ -0,0 +1,3 @@
+# `Visualization`
+
+::: agents.extensions.visualization

docs/ref/logger.md

@@ -0,0 +1,3 @@
+# `Logger`
+
+::: agents.logger

docs/ref/models/chatcmpl_converter.md

@@ -0,0 +1,3 @@
+# `Chatcmpl Converter`
+
+::: agents.models.chatcmpl_converter

docs/ref/models/chatcmpl_helpers.md

@@ -0,0 +1,3 @@
+# `Chatcmpl Helpers`
+
+::: agents.models.chatcmpl_helpers

docs/ref/models/chatcmpl_stream_handler.md

@@ -0,0 +1,3 @@
+# `Chatcmpl Stream Handler`
+
+::: agents.models.chatcmpl_stream_handler

docs/ref/models/fake_id.md

@@ -0,0 +1,3 @@
+# `Fake Id`
+
+::: agents.models.fake_id

docs/ref/models/multi_provider.md

@@ -0,0 +1,3 @@
+# `Multi Provider`
+
+::: agents.models.multi_provider

docs/ref/models/openai_provider.md

@@ -0,0 +1,3 @@
+# `OpenAI Provider`
+
+::: agents.models.openai_provider

docs/ref/prompts.md

@@ -0,0 +1,3 @@
+# `Prompts`
+
+::: agents.prompts

docs/ref/strict_schema.md

@@ -0,0 +1,3 @@
+# `Strict Schema`
+
+::: agents.strict_schema

docs/ref/tool_context.md

@@ -0,0 +1,3 @@
+# `Tool Context`
+
+::: agents.tool_context

docs/ref/tracing/logger.md

@@ -0,0 +1,3 @@
+# `Logger`
+
+::: agents.tracing.logger

docs/ref/tracing/provider.md

@@ -0,0 +1,3 @@
+# `Provider`
+
+::: agents.tracing.provider

docs/ref/version.md

@@ -0,0 +1,3 @@
+# `Version`
+
+::: agents.version

docs/ref/voice/imports.md

@@ -0,0 +1,3 @@
+# `Imports`
+
+::: agents.voice.imports

docs/ref/voice/models/openai_model_provider.md

@@ -0,0 +1,3 @@
+# `OpenAI Model Provider`
+
+::: agents.voice.models.openai_model_provider

docs/scripts/generate_ref_files.py

@@ -0,0 +1,76 @@
+#!/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
+from string import capwords
+
+# ---- 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 capwords(cleaned)
+
+# ---- 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()

mkdocs.yml

@@ -86,6 +86,7 @@ plugins:
                     - ref/memory.md
                     - ref/repl.md
                     - ref/tool.md
+                    - ref/tool_context.md
                     - ref/result.md
                     - ref/stream_events.md
                     - ref/handoffs.md