chore: add Markdown API doc generation tooling

Add a docs-api Makefile target, scripts/gen_api_docs.py, and
pydoc-markdown.yml to render the API reference into docs/api/; gitignore
the generated output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

.gitignore

@@ -12,3 +12,8 @@ build/
 .ruff_cache/
 .pyright/
 .DS_Store
+
+# Generated API docs (see Makefile target `docs-api`). Re-rendered from
+# docstrings by scripts/gen_api_docs.py; the site at ../www builds
+# fresh from python-sdk/docs/**/*.md, so we don't track the output here.
+docs/api/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: diagrams build clean publish test
+.PHONY: diagrams build clean publish test docs-api
 
 DIAGRAMS := arch-overview session-lifecycle job-lifecycle capability-negotiation heartbeat-ack result-chunk-progress
 DIAGRAM_DIR := docs/diagrams
@@ -30,3 +30,19 @@ publish: build
 # but uses `uv run` so the lockfile is honored.
 test:
 	uv run pytest --cov --cov-branch --cov-report=xml
+
+# Generate Markdown API docs from docstrings into docs/api/.
+# The site at ../www ingests `<lang>-sdk/docs/**/*.md` at build time,
+# so this target writes one .md per module under docs/api/. Output is
+# .gitignored; re-run whenever public API docstrings change.
+#
+# Requires pydoc-markdown on PATH with arcp's runtime deps injected:
+#   pipx install pydoc-markdown
+#   pipx inject pydoc-markdown pydantic structlog python-ulid websockets \
+#     click aiosqlite 'pyjwt[crypto]' opentelemetry-api httpx
+docs-api:
+	@command -v pydoc-markdown >/dev/null 2>&1 || { \
+		echo "error: pydoc-markdown not found; install with: pipx install pydoc-markdown"; \
+		exit 1; \
+	}
+	python3 scripts/gen_api_docs.py

pydoc-markdown.yml

@@ -0,0 +1,53 @@
+# Base pydoc-markdown configuration for arcp.
+#
+# This is the shared loader/processor block consumed by scripts/gen_api_docs.py.
+# The script iterates over every public module under src/arcp, overrides the
+# `modules` list per-invocation, and writes the rendered output to
+# docs/api/<dotted.path>.md so the site generator at ../www can ingest it as
+# `<lang>-sdk/docs/**/*.md`.
+loaders:
+  - type: python
+    search_path: [src]
+processors:
+  # Drop `from x import y` re-exports (docspec calls these Indirection)
+  # so module pages don't list every imported name as if it were a
+  # module-level definition. Keep dunder methods (`__init__`, etc.)
+  # because they carry useful signatures. `do_not_filter_modules`
+  # keeps the module nodes themselves even when their content is
+  # otherwise filtered out (e.g. arcp.client which is purely
+  # re-exports).
+  - type: filter
+    expression: obj.__class__.__name__ != 'Indirection' and name not in ('__all__', '__path__', '__annotations__', '__name__') and (not name.startswith('_') or (name.startswith('__') and name.endswith('__')))
+    documented_only: false
+    do_not_filter_modules: true
+    skip_empty_modules: false
+  - type: smart
+  - type: crossref
+renderer:
+  type: markdown
+  render_module_header: true
+  render_toc: true
+  render_toc_title: ''
+  insert_header_anchors: false
+  descriptive_class_title: false
+  add_method_class_prefix: true
+  add_member_class_prefix: true
+  classdef_with_decorators: true
+  signature_with_decorators: true
+  signature_class_prefix: true
+  signature_with_def: true
+  signature_python_help_style: false
+  # yapf in pydoc-markdown 4.8 does not parse some modern Python syntax
+  # (e.g. PEP 695 type params, certain default expressions) and will
+  # crash with `YapfError: expected '('`. We disable yapf-based
+  # signature reflow; pydoc-markdown still emits a clean ```python
+  # fenced block.
+  format_code: false
+  use_fixed_header_levels: true
+  header_level_by_type:
+    Module: 1
+    Class: 2
+    Method: 3
+    Function: 2
+    Variable: 3
+    Data: 3

scripts/gen_api_docs.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Generate Markdown API docs for arcp.
+
+For every Python module under ``src/arcp``, this script runs
+``pydoc-markdown`` once and writes the rendered Markdown to
+``docs/api/<dotted.module.path>.md`` -- one file per module. The site
+at ``../www`` ingests ``python-sdk/docs/**/*.md`` at build time, so
+the output deliberately stays as flat Markdown with no framework
+trappings (no Hugo/Docusaurus front matter, no HTML).
+
+Usage:
+    python3 scripts/gen_api_docs.py
+
+The shared loader/processor/renderer config lives in
+``pydoc-markdown.yml`` next to this script's parent. We invoke
+``pydoc-markdown <inline-yaml>`` per module so each invocation only
+emits one module's documentation; that gives us one ``.md`` per
+module without depending on the mkdocs/docusaurus multi-page
+renderers, which would drag in framework-specific output.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / "src" / "arcp"
+OUT = ROOT / "docs" / "api"
+CONFIG = ROOT / "pydoc-markdown.yml"
+
+
+def discover_modules() -> list[str]:
+    """Return every importable module under ``src/arcp`` as dotted paths."""
+    modules: list[str] = []
+    for path in sorted(SRC.rglob("*.py")):
+        rel = path.relative_to(SRC.parent)  # e.g. arcp/_client/client.py
+        parts = list(rel.with_suffix("").parts)
+        if parts[-1] == "__init__":
+            parts = parts[:-1]
+        if not parts or parts[-1] == "__main__":
+            # Skip __main__ (entrypoint shim, no real API surface) and any
+            # bare package root that collapsed to nothing.
+            if parts and parts[-1] == "__main__":
+                continue
+            if not parts:
+                continue
+        modules.append(".".join(parts))
+    # Deduplicate while preserving order.
+    seen: set[str] = set()
+    unique: list[str] = []
+    for m in modules:
+        if m not in seen:
+            seen.add(m)
+            unique.append(m)
+    return unique
+
+
+def render(module: str) -> str:
+    """Run pydoc-markdown for a single module and return its Markdown."""
+    # Inline YAML override: keep the shared config but pin `modules` to one
+    # name. pydoc-markdown accepts a YAML string as the CONFIG arg.
+    config_yaml = CONFIG.read_text(encoding="utf-8")
+    # Append a `modules` entry to the python loader. The base config has
+    # one loader with `search_path: [src]`; we add `modules: [...]` to it.
+    override = config_yaml.replace(
+        "    search_path: [src]",
+        f"    search_path: [src]\n    modules: ['{module}']",
+        1,
+    )
+    result = subprocess.run(
+        ["pydoc-markdown", override],
+        cwd=ROOT,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout
+
+
+def main() -> int:
+    if shutil.which("pydoc-markdown") is None:
+        print(
+            "error: `pydoc-markdown` not on PATH. Install with "
+            "`pipx install pydoc-markdown` and run `pipx inject "
+            "pydoc-markdown <runtime deps>` so arcp is importable.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if OUT.exists():
+        shutil.rmtree(OUT)
+    OUT.mkdir(parents=True, exist_ok=True)
+
+    modules = discover_modules()
+    if not modules:
+        print("error: no modules discovered under src/arcp", file=sys.stderr)
+        return 1
+
+    print(f"Rendering {len(modules)} modules -> {OUT.relative_to(ROOT)}/")
+    for module in modules:
+        target = OUT / f"{module}.md"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            markdown = render(module)
+        except subprocess.CalledProcessError as exc:
+            print(f"  FAIL  {module}", file=sys.stderr)
+            print(exc.stderr, file=sys.stderr)
+            return exc.returncode
+        if not markdown.strip():
+            print(f"  skip  {module} (empty)")
+            continue
+        target.write_text(markdown, encoding="utf-8")
+        print(f"  ok    {module} -> {target.relative_to(ROOT)}")
+
+    # Write an index so the site has a stable landing page for /api/.
+    index = OUT / "README.md"
+    lines = ["# Python SDK API reference", "", "Auto-generated from docstrings in `src/arcp`.", ""]
+    for module in modules:
+        md_path = f"{module}.md"
+        lines.append(f"- [`{module}`]({md_path})")
+    index.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"  ok    index -> {index.relative_to(ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())