Add automation script to generate mkdocstrings files (#1048)

seratch · web-flow · commit c5d50109c470 · 2025-07-22T08:35:18.000+09:00
This pull request adds a new script for docs, which generates missing `ref/**/*.md` files. The script can be executed when you run `make build-docs` command. The script does not do: - overwrite the existing ones - create files for _XXX.py and `__init__.py` Note that the title part is generated like `tool_context` to `Tool Context`. `openai_provider` will be `Openai Provider`, so some of them needs a little manual work to adjust. The direct need is to add `tool_context.md` for #1043 but it should be useful for future maintenance.
diff --git a/Makefile b/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
diff --git a/docs/ref/computer.md b/docs/ref/computer.md
@@ -0,0 +1,3 @@
+# `Computer`
+
+::: agents.computer
diff --git a/docs/ref/extensions/models/litellm_model.md b/docs/ref/extensions/models/litellm_model.md
@@ -0,0 +1,3 @@
+# `LiteLLM Model`
+
+::: agents.extensions.models.litellm_model
diff --git a/docs/ref/extensions/models/litellm_provider.md b/docs/ref/extensions/models/litellm_provider.md
@@ -0,0 +1,3 @@
+# `LiteLLM Provider`
+
+::: agents.extensions.models.litellm_provider
diff --git a/docs/ref/extensions/visualization.md b/docs/ref/extensions/visualization.md
@@ -0,0 +1,3 @@
+# `Visualization`
+
+::: agents.extensions.visualization
diff --git a/docs/ref/logger.md b/docs/ref/logger.md
@@ -0,0 +1,3 @@
+# `Logger`
+
+::: agents.logger
diff --git a/docs/ref/models/chatcmpl_converter.md b/docs/ref/models/chatcmpl_converter.md
@@ -0,0 +1,3 @@
+# `Chatcmpl Converter`
+
+::: agents.models.chatcmpl_converter
diff --git a/docs/ref/models/chatcmpl_helpers.md b/docs/ref/models/chatcmpl_helpers.md
@@ -0,0 +1,3 @@
+# `Chatcmpl Helpers`
+
+::: agents.models.chatcmpl_helpers
diff --git a/docs/ref/models/chatcmpl_stream_handler.md b/docs/ref/models/chatcmpl_stream_handler.md
@@ -0,0 +1,3 @@
+# `Chatcmpl Stream Handler`
+
+::: agents.models.chatcmpl_stream_handler
diff --git a/docs/ref/models/fake_id.md b/docs/ref/models/fake_id.md
@@ -0,0 +1,3 @@
+# `Fake Id`
+
+::: agents.models.fake_id
diff --git a/docs/ref/models/multi_provider.md b/docs/ref/models/multi_provider.md
@@ -0,0 +1,3 @@
+# `Multi Provider`
+
+::: agents.models.multi_provider
diff --git a/docs/ref/models/openai_provider.md b/docs/ref/models/openai_provider.md
@@ -0,0 +1,3 @@
+# `OpenAI Provider`
+
+::: agents.models.openai_provider
diff --git a/docs/ref/prompts.md b/docs/ref/prompts.md
@@ -0,0 +1,3 @@
+# `Prompts`
+
+::: agents.prompts
diff --git a/docs/ref/strict_schema.md b/docs/ref/strict_schema.md
@@ -0,0 +1,3 @@
+# `Strict Schema`
+
+::: agents.strict_schema
diff --git a/docs/ref/tool_context.md b/docs/ref/tool_context.md
@@ -0,0 +1,3 @@
+# `Tool Context`
+
+::: agents.tool_context
diff --git a/docs/ref/tracing/logger.md b/docs/ref/tracing/logger.md
@@ -0,0 +1,3 @@
+# `Logger`
+
+::: agents.tracing.logger
diff --git a/docs/ref/tracing/provider.md b/docs/ref/tracing/provider.md
@@ -0,0 +1,3 @@
+# `Provider`
+
+::: agents.tracing.provider
diff --git a/docs/ref/version.md b/docs/ref/version.md
@@ -0,0 +1,3 @@
+# `Version`
+
+::: agents.version
diff --git a/docs/ref/voice/imports.md b/docs/ref/voice/imports.md
@@ -0,0 +1,3 @@
+# `Imports`
+
+::: agents.voice.imports
diff --git a/docs/ref/voice/models/openai_model_provider.md b/docs/ref/voice/models/openai_model_provider.md
@@ -0,0 +1,3 @@
+# `OpenAI Model Provider`
+
+::: agents.voice.models.openai_model_provider
diff --git a/docs/scripts/generate_ref_files.py b/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()
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -89,6 +89,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

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Computer`
	`2`	`+`
	`3`	`+::: agents.computer`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `LiteLLM Model`
	`2`	`+`
	`3`	`+::: agents.extensions.models.litellm_model`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `LiteLLM Provider`
	`2`	`+`
	`3`	`+::: agents.extensions.models.litellm_provider`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Visualization`
	`2`	`+`
	`3`	`+::: agents.extensions.visualization`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Logger`
	`2`	`+`
	`3`	`+::: agents.logger`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Chatcmpl Converter`
	`2`	`+`
	`3`	`+::: agents.models.chatcmpl_converter`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Chatcmpl Helpers`
	`2`	`+`
	`3`	`+::: agents.models.chatcmpl_helpers`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Chatcmpl Stream Handler`
	`2`	`+`
	`3`	`+::: agents.models.chatcmpl_stream_handler`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# `Fake Id`
	`2`	`+`
	`3`	`+::: agents.models.fake_id`