1
+#!/usr/bin/env python3
2
+"""
3
+Python SDK Documentation Generator
4
+
5
+Generates MDX documentation from Python source code using griffe.
6
+Output is written to the fumadocs content directory.
7
+
8
+Run: cd python && uv run --with griffe python scripts/generate-docs.py
9
+"""
10
+
11
+from __future__ import annotations
12
+
13
+import json
14
+import re
15
+import shutil
16
+from pathlib import Path
17
+from typing import Any
18
+
19
+try:
20
+ import griffe
21
+except ImportError:
22
+ print("Error: griffe not installed. Run: pip install griffe")
23
+ raise SystemExit(1)
24
+
25
+# Paths
26
+SCRIPT_DIR = Path(__file__).parent
27
+PACKAGE_DIR = SCRIPT_DIR.parent
28
+OUTPUT_DIR = PACKAGE_DIR.parent / "fumadocs" / "content" / "reference" / "sdk-reference" / "python"
29
+
30
+# GitHub base URL for source links
31
+GITHUB_BASE = "https://github.com/composiohq/composio/blob/next/python"
32
+
33
+# Decorators to document
34
+DECORATORS_TO_DOCUMENT = [
35
+ ("before_execute", "composio.core.models._modifiers"),
36
+ ("after_execute", "composio.core.models._modifiers"),
37
+ ("schema_modifier", "composio.core.models._modifiers"),
38
+]
39
+
40
+# Classes to skip (internal/helper classes)
41
+SKIP_CLASSES = {"WithLogger", "SDKConfig", "TProvider"}
42
+
43
+# Expected classes to document (maps class name -> property name on Composio)
44
+EXPECTED_CLASSES = {
45
+ "Tools": "tools",
46
+ "Toolkits": "toolkits",
47
+ "Triggers": "triggers",
48
+ "ConnectedAccounts": "connected_accounts",
49
+ "AuthConfigs": "auth_configs",
50
+}
51
+
52
+# Modules to search for classes
53
+CLASS_MODULES = [
54
+ "core.models.tools",
55
+ "core.models.toolkits",
56
+ "core.models.triggers",
57
+ "core.models.connected_accounts",
58
+ "core.models.auth_configs",
59
+]
60
+
61
+
62
+def to_kebab_case(name: str) -> str:
63
+ """Convert PascalCase to kebab-case."""
64
+ s1 = re.sub("(.)([A-Z][a-z]+)", r"\1-\2", name)
65
+ return re.sub("([a-z0-9])([A-Z])", r"\1-\2", s1).lower()
66
+
67
+
68
+def escape_yaml_string(s: str) -> str:
69
+ """Escape a string for YAML frontmatter."""
70
+ if any(c in s for c in [':', '"', "'", '\n', '#', '{', '}']):
71
+ return f'"{s.replace(chr(34), chr(92)+chr(34))}"'
72
+ return s
73
+
74
+
75
+def get_source_link(obj: griffe.Object) -> str | None:
76
+ """Get GitHub source link for an object."""
77
+ if not hasattr(obj, "filepath") or not obj.filepath:
78
+ return None
79
+ try:
80
+ rel_path = Path(obj.filepath).relative_to(PACKAGE_DIR)
81
+ except ValueError:
82
+ return None
83
+ line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
84
+ return f"{GITHUB_BASE}/{rel_path}#L{line}"
85
+
86
+
87
+def format_type(annotation: Any) -> str:
88
+ """Format a type annotation to readable string."""
89
+ if annotation is None:
90
+ return "Any"
91
+
92
+ type_str = str(annotation)
93
+ # Clean up common prefixes
94
+ type_str = type_str.replace("typing.", "").replace("typing_extensions.", "")
95
+ type_str = type_str.replace("composio.client.types.", "")
96
+ type_str = re.sub(r'\bt\.', '', type_str)
97
+ type_str = re.sub(r'\bte\.', '', type_str) # typing_extensions alias
98
+ type_str = re.sub(r'Optional\[([^\]]+)\]', r'\1 | None', type_str)
99
+ # Clean up Unpack to just show the type
100
+ type_str = re.sub(r'Unpack\[([^\]]+)\]', r'\1', type_str)
101
+
102
+ # Truncate very long types
103
+ if len(type_str) > 60:
104
+ return type_str[:57] + "..."
105
+ return type_str
106
+
107
+
108
+def parse_docstring(docstring: str | None) -> dict[str, Any]:
109
+ """Parse docstring into components."""
110
+ if not docstring:
111
+ return {"description": "", "params": {}, "returns": None, "examples": []}
112
+
113
+ lines = docstring.strip().split("\n")
114
+ description_lines = []
115
+ params: dict[str, str] = {}
116
+ returns = None
117
+ examples: list[str] = []
118
+
119
+ section = "description"
120
+ current_param = None
121
+ example_lines: list[str] = []
122
+
123
+ for line in lines:
124
+ stripped = line.strip()
125
+
126
+ # Check for :param name: description
127
+ param_match = re.match(r":param\s+(\w+):\s*(.*)", stripped)
128
+ if param_match:
129
+ section = "params"
130
+ current_param = param_match.group(1)
131
+ params[current_param] = param_match.group(2)
132
+ continue
133
+
134
+ # Check for :returns: or :return:
135
+ return_match = re.match(r":returns?:\s*(.*)", stripped)
136
+ if return_match:
137
+ section = "returns"
138
+ returns = return_match.group(1)
139
+ continue
140
+
141
+ # Check for Example section
142
+ if stripped.lower().startswith("example"):
143
+ section = "examples"
144
+ continue
145
+
146
+ # Add to appropriate section
147
+ if section == "description":
148
+ description_lines.append(stripped)
149
+ elif section == "params" and current_param and stripped:
150
+ params[current_param] += " " + stripped
151
+ elif section == "returns" and returns and stripped:
152
+ returns += " " + stripped
153
+ elif section == "examples":
154
+ example_lines.append(line)
155
+
156
+ if example_lines:
157
+ examples.append("\n".join(example_lines).strip())
158
+
159
+ return {
160
+ "description": " ".join(description_lines).strip(),
161
+ "params": params,
162
+ "returns": returns,
163
+ "examples": examples,
164
+ }
165
+
166
+
167
+def extract_class_info(cls: griffe.Class, class_name: str, config: dict) -> dict[str, Any]:
168
+ """Extract documentation from a class."""
169
+ doc = parse_docstring(cls.docstring.value if cls.docstring else None)
170
+
171
+ info = {
172
+ "name": class_name,
173
+ "access": config.get("access"),
174
+ "source_link": get_source_link(cls),
175
+ "description": doc["description"],
176
+ "properties": [],
177
+ "methods": [],
178
+ }
179
+
180
+ # Extract properties/attributes
181
+ for name, member in cls.members.items():
182
+ if name.startswith("_"):
183
+ continue
184
+ if isinstance(member, griffe.Attribute):
185
+ attr_doc = member.docstring.value if member.docstring else ""
186
+ info["properties"].append({
187
+ "name": name,
188
+ "type": format_type(member.annotation),
189
+ "description": attr_doc.strip() if attr_doc else "",
190
+ })
191
+
192
+ # Extract methods
193
+ for name, member in cls.members.items():
194
+ if name.startswith("_"):
195
+ continue
196
+ if isinstance(member, griffe.Function):
197
+ method_doc = parse_docstring(member.docstring.value if member.docstring else None)
198
+
199
+ params = []
200
+ for p in member.parameters:
201
+ if p.name in ("self", "cls"):
202
+ continue
203
+ params.append({
204
+ "name": p.name,
205
+ "type": format_type(p.annotation),
206
+ "optional": p.default is not None,
207
+ "description": method_doc["params"].get(p.name, ""),
208
+ })
209
+
210
+ info["methods"].append({
211
+ "name": name,
212
+ "source_link": get_source_link(member),
213
+ "description": method_doc["description"],
214
+ "parameters": params,
215
+ "return_type": format_type(member.returns),
216
+ "return_description": method_doc["returns"],
217
+ "examples": method_doc["examples"],
218
+ })
219
+
220
+ return info
221
+
222
+
223
+def generate_class_mdx(info: dict[str, Any], prop_to_class: dict[str, str] = None) -> str:
224
+ """Generate MDX for a class."""
225
+ lines = []
226
+
227
+ # Frontmatter
228
+ desc = info["description"].split("\n")[0] if info["description"] else f"{info['name']} class"
229
+ if len(desc) > 150:
230
+ desc = desc[:147] + "..."
231
+
232
+ lines.append("---")
233
+ lines.append(f"title: {info['name']}")
234
+ lines.append(f"description: {escape_yaml_string(desc)}")
235
+ lines.append("---")
236
+ lines.append("")
237
+
238
+ source_link = info.get("source_link", "")
239
+
240
+ # Properties - as table for Composio class
241
+ if prop_to_class:
242
+ prop_rows = []
243
+ for prop in info["properties"]:
244
+ prop_name = prop["name"]
245
+ if prop_name in prop_to_class:
246
+ class_name = prop_to_class[prop_name]
247
+ link = f"/reference/sdk-reference/python/{to_kebab_case(class_name)}"
248
+ prop_rows.append(f"| [`{prop_name}`]({link}) | `{class_name}` |")
249
+
250
+ if prop_rows:
251
+ lines.append("## Properties")
252
+ lines.append("")
253
+ lines.append("| Name | Type |")
254
+ lines.append("|------|------|")
255
+ lines.extend(prop_rows)
256
+ lines.append("")
257
+
258
+ # Methods
259
+ if info["methods"]:
260
+ lines.append("## Methods")
261
+ lines.append("")
262
+
263
+ for method in info["methods"]:
264
+ lines.append(f"### {method['name']}()")
265
+ lines.append("")
266
+
267
+ if method["description"]:
268
+ lines.append(method["description"])
269
+ lines.append("")
270
+
271
+ # Signature
272
+ params_str = ", ".join(
273
+ f"{p['name']}: {p['type']}" + (" = ..." if p["optional"] else "")
274
+ for p in method["parameters"]
275
+ )
276
+ ret_type = method["return_type"] if method["return_type"] != "Any" else ""
277
+ sig = f"def {method['name']}({params_str})"
278
+ if ret_type:
279
+ sig += f" -> {ret_type}"
280
+
281
+ lines.append("```python")
282
+ lines.append(sig)
283
+ lines.append("```")
284
+ lines.append("")
285
+
286
+ # Parameters
287
+ if method["parameters"]:
288
+ lines.append("**Parameters**")
289
+ lines.append("")
290
+ lines.append("| Name | Type |")
291
+ lines.append("|------|------|")
292
+ for p in method["parameters"]:
293
+ opt = "?" if p["optional"] else ""
294
+ safe_type = p["type"].replace("|", "\\|")
295
+ lines.append(f"| `{p['name']}{opt}` | `{safe_type}` |")
296
+ lines.append("")
297
+
298
+ # Returns
299
+ if method["return_type"] and method["return_type"] not in ("None", "Any"):
300
+ ret_desc = method["return_description"] or ""
301
+ lines.append("**Returns**")
302
+ lines.append("")
303
+ if ret_desc:
304
+ lines.append(f"`{method['return_type']}` — {ret_desc}")
305
+ else:
306
+ lines.append(f"`{method['return_type']}`")
307
+ lines.append("")
308
+
309
+ # Examples
310
+ if method["examples"]:
311
+ lines.append("**Example**")
312
+ lines.append("")
313
+ for ex in method["examples"]:
314
+ lines.append("```python")
315
+ lines.append(ex)
316
+ lines.append("```")
317
+ lines.append("")
318
+
319
+ lines.append("---")
320
+ lines.append("")
321
+
322
+ # Source link at bottom
323
+ if source_link:
324
+ lines.append(f"[View source]({source_link})")
325
+ lines.append("")
326
+
327
+ return "\n".join(lines)
328
+
329
+
330
+def generate_index_mdx(classes: list[dict], decorators: list[dict]) -> str:
331
+ """Generate index page."""
332
+
333
+ # Classes table
334
+ class_rows = []
335
+ for c in classes:
336
+ link = f"/reference/sdk-reference/python/{to_kebab_case(c['name'])}"
337
+ desc = c["description"][:80] + "..." if len(c["description"]) > 80 else c["description"]
338
+ class_rows.append(f"| [`{c['name']}`]({link}) | {desc} |")
339
+
340
+ # Decorators section
341
+ dec_section = ""
342
+ if decorators:
343
+ dec_lines = ["## Decorators", ""]
344
+ for d in decorators:
345
+ dec_lines.append(f"### {d['name']}")
346
+ dec_lines.append("")
347
+ if d["description"]:
348
+ dec_lines.append(d["description"])
349
+ dec_lines.append("")
350
+ if d["source_link"]:
351
+ dec_lines.append(f"[View source]({d['source_link']})")
352
+ dec_lines.append("")
353
+ # Signature
354
+ params = ", ".join(
355
+ f"{p['name']}: {p['type']}" + (" = ..." if p["optional"] else "")
356
+ for p in d["parameters"]
357
+ )
358
+ dec_lines.append("```python")
359
+ dec_lines.append(f"@{d['name']}({params})")
360
+ dec_lines.append("def my_modifier(...):")
361
+ dec_lines.append(" ...")
362
+ dec_lines.append("```")
363
+ dec_lines.append("")
364
+ dec_section = "\n".join(dec_lines)
365
+
366
+ return f'''---
367
+title: Python SDK Reference
368
+description: API reference for the Composio Python SDK
369
+---
370
+
371
+# Python SDK Reference
372
+
373
+Complete API reference for the `composio` Python package.
374
+
375
+## Installation
376
+
377
+```bash
378
+pip install composio
379
+```
380
+
381
+Or with uv:
382
+
383
+```bash
384
+uv add composio
385
+```
386
+
387
+## Classes
388
+
389
+| Class | Description |
390
+|-------|-------------|
391
+{chr(10).join(class_rows)}
392
+
393
+## Quick Start
394
+
395
+```python
396
+from composio import Composio
397
+
398
+composio = Composio(api_key="your-api-key")
399
+
400
+# Get tools for a user
401
+tools = composio.tools.get("user-123", toolkits=["github"])
402
+
403
+# Execute a tool
404
+result = composio.tools.execute(
405
+ "GITHUB_GET_REPOS",
406
+ arguments={{"owner": "composio"}},
407
+ user_id="user-123"
408
+)
409
+```
410
+
411
+{dec_section}
412
+'''
413
+
414
+
415
+def main():
416
+ print("Starting Python SDK documentation generation...\n")
417
+ print(f"Output: {OUTPUT_DIR}\n")
418
+
419
+ # Clean output
420
+ if OUTPUT_DIR.exists():
421
+ shutil.rmtree(OUTPUT_DIR)
422
+ OUTPUT_DIR.mkdir(parents=True)
423
+
424
+ # Load package
425
+ print("Loading composio package...")
426
+ try:
427
+ package = griffe.load("composio", search_paths=[str(PACKAGE_DIR)])
428
+ except Exception as e:
429
+ print(f"Error: {e}")
430
+ raise SystemExit(1)
431
+
432
+ # Find Composio class
433
+ composio_cls = package.members["sdk"].members["Composio"]
434
+ print(" Found Composio class")
435
+
436
+ # Discover classes from EXPECTED_CLASSES
437
+ classes_to_doc = {"Composio": {"cls": composio_cls, "access": None, "prop": None}}
438
+ prop_to_class = {} # Maps property name -> class name
439
+
440
+ for module_name in CLASS_MODULES:
441
+ try:
442
+ parts = module_name.split(".")
443
+ current = package
444
+ for part in parts:
445
+ current = current.members[part]
446
+
447
+ # Find expected classes in this module
448
+ for class_name, prop_name in EXPECTED_CLASSES.items():
449
+ if class_name in current.members:
450
+ cls = current.members[class_name]
451
+ if isinstance(cls, griffe.Class):
452
+ classes_to_doc[class_name] = {
453
+ "cls": cls,
454
+ "access": f"composio.{prop_name}",
455
+ "prop": prop_name,
456
+ }
457
+ prop_to_class[prop_name] = class_name
458
+ print(f" Found {class_name} (via composio.{prop_name})")
459
+ except (KeyError, AttributeError):
460
+ continue
461
+
462
+ # Generate docs for each class
463
+ documented_classes = []
464
+
465
+ for class_name, config in classes_to_doc.items():
466
+ cls = config["cls"]
467
+ print(f" Processing {class_name}...")
468
+
469
+ info = extract_class_info(cls, class_name, {"access": config["access"]})
470
+
471
+ # Only Composio gets prop_to_class for linking
472
+ if class_name == "Composio":
473
+ mdx = generate_class_mdx(info, prop_to_class)
474
+ else:
475
+ mdx = generate_class_mdx(info, None)
476
+
477
+ file_path = OUTPUT_DIR / f"{to_kebab_case(class_name)}.mdx"
478
+ file_path.write_text(mdx)
479
+
480
+ documented_classes.append({
481
+ "name": class_name,
482
+ "description": info["description"] or f"{class_name} class",
483
+ })
484
+
485
+ # Process decorators
486
+ decorators = []
487
+ for dec_name, dec_module in DECORATORS_TO_DOCUMENT:
488
+ module_path = dec_module.split(".")
489
+ current = package
490
+
491
+ for part in module_path[1:]:
492
+ if part in current.members:
493
+ current = current.members[part]
494
+
495
+ if dec_name in current.members:
496
+ func = current.members[dec_name]
497
+ if isinstance(func, griffe.Function):
498
+ print(f" Processing decorator {dec_name}...")
499
+ doc = parse_docstring(func.docstring.value if func.docstring else None)
500
+
501
+ params = []
502
+ for p in func.parameters:
503
+ if p.name in ("self", "cls"):
504
+ continue
505
+ params.append({
506
+ "name": p.name,
507
+ "type": format_type(p.annotation),
508
+ "optional": p.default is not None,
509
+ "description": doc["params"].get(p.name, ""),
510
+ })
511
+
512
+ decorators.append({
513
+ "name": dec_name,
514
+ "source_link": get_source_link(func),
515
+ "description": doc["description"],
516
+ "parameters": params,
517
+ })
518
+
519
+ # Generate index
520
+ index_content = generate_index_mdx(documented_classes, decorators)
521
+ (OUTPUT_DIR / "index.mdx").write_text(index_content)
522
+
523
+ # Generate meta.json
524
+ meta = {
525
+ "title": "Python SDK",
526
+ "pages": [to_kebab_case(c["name"]) for c in documented_classes],
527
+ }
528
+ (OUTPUT_DIR / "meta.json").write_text(json.dumps(meta, indent=2))
529
+
530
+ print(f"\nDone! Generated {len(documented_classes)} class docs + index")
531
+ print(f" Classes: {', '.join(c['name'] for c in documented_classes)}")
532
+ print(f" Decorators: {', '.join(d['name'] for d in decorators)}")
533
+
534
+
535
+if __name__ == "__main__":
536
+ main()