trycua--cua/scripts/docs-generators

Documentation Generators

This directory contains auto-documentation generators for the Cua libraries. These generators ensure that documentation stays synchronized with source code.

Architecture

scripts/docs-generators/
├── config.json         # Central configuration for all generators
├── runner.ts           # Main orchestrator that runs generators
├── cua-driver.ts       # cua-driver (Rust) generator
├── lume.ts             # Lume (Swift) generator
├── cua-cli.ts          # Cua CLI (TypeScript) generator (planned)
├── mcp-server.ts       # MCP Server (Python) generator (planned)
├── python-sdk.ts       # Python SDK generator (planned)
├── typescript-sdk.ts   # TypeScript SDK generator (planned)
└── README.md           # This file

Quick Start

# Generate all documentation
npm run docs:generate

# Check for drift (CI mode)
npm run docs:check

# List all configured generators
npm run docs:list

# Generate specific library docs
npx tsx scripts/docs-generators/runner.ts --library lume

How It Works

1. config.json defines all libraries that need documentation generation:

   • Source paths to watch
   • Output paths for generated docs
   • Generator scripts to run
   • Build commands (if needed)

2. runner.ts orchestrates generation:

   • Reads config.json
   • Detects changed files (in CI)
   • Runs appropriate generators
   • Reports success/failure

3. Library-specific generators (e.g., lume.ts):

   • Extract metadata from source code
   • Generate MDX documentation
   • Handle language-specific concerns

Adding a New Library

1. Add configuration to config.json:

   {
     "generators": {
       "my-library": {
         "name": "My Library",
         "language": "python",
         "sourcePath": "libs/my-library/src",
         "docsOutputPath": "docs/content/docs/cua/reference/my-library",
         "generatorScript": "scripts/docs-generators/my-library.ts",
         "watchPaths": ["libs/my-library/src/**/*.py"],
         "enabled": true
       }
     }
   }
   

2. Create generator script (e.g., my-library.ts):

   #!/usr/bin/env npx tsx
   // Follow the pattern in lume.ts
   

3. Update CI workflow if needed (paths are usually auto-detected from config)

Extraction Methods

Different libraries use different extraction methods:

Language	Method	Description
Rust	dump-docs	Built-in command that outputs JSON
Swift	dump-docs	Built-in command that outputs JSON
TypeScript	yargs-parse	Parse yargs CLI definitions
Python	argparse-introspection	Introspect argparse commands
Python	sphinx-autodoc	Generate from docstrings
TypeScript	typedoc	Generate from TSDoc comments

CI Integration

The .github/workflows/docs-sync-check.yml workflow:

1. Detects which libraries have changes
2. Only runs generators for changed libraries
3. Fails if documentation is out of sync
4. Provides helpful fix instructions

Generator Status

Generator	Status	Notes
cua-driver	✅ Implemented	CLI + MCP tools
lume	✅ Implemented	CLI + HTTP API
cua-cli	⏸️ Planned	Needs yargs introspection
mcp-server	⏸️ Planned	Needs MCP tool extraction
computer-sdk-python	⏸️ Planned	Needs Sphinx/pydoc
computer-sdk-typescript	⏸️ Planned	Needs TypeDoc
agent-sdk-python	⏸️ Planned	Needs Sphinx/pydoc
agent-sdk-typescript	⏸️ Planned	Needs TypeDoc

Development

To test generators locally:

# Run with verbose output
DEBUG=1 npx tsx scripts/docs-generators/runner.ts

# Generate only one library
npx tsx scripts/docs-generators/runner.ts --library lume

# Check without modifying files
npx tsx scripts/docs-generators/runner.ts --check