waygrounddocgen 0.2.0

A language-agnostic documentation generator and evaluator using Cursor AI

waygrounddocgen

A language-agnostic CLI tool that leverages Cursor AI to automatically discover modules in any codebase, generate comprehensive documentation, and evaluate documentation quality.

Features

• 🔍 Auto-Discovery: Uses Cursor AI to identify logical modules/components in any language
• 📝 Parallel Generation: Runs multiple Cursor tasks simultaneously for faster documentation
• ✅ Quality Evaluation: Two-phase evaluation with automated checks + LLM-as-judge
• 🔄 Auto-Retry: Automatically regenerate documentation that fails evaluation
• 🌐 Language Agnostic: Works with TypeScript, Python, Go, Java, Rust, and more
• 📋 Customizable Prompts: Built-in prompt templates with support for customization
• 📊 Progress Tracking: Clear output showing progress and results

Prerequisites

1. Python 3.8+ installed
2. Cursor CLI installed and available in PATH

   curl https://cursor.com/install -fsS | bash
   

   Or from GUI: Cursor → Settings → General → Command Line → Install

Installation

From PyPI (Recommended)

pip install waygrounddocgen

# With evaluation support (includes anthropic for LLM-as-judge)
pip install waygrounddocgen[eval]

From Source

git clone https://github.com/gauravmadan/waygrounddocgen.git
cd waygrounddocgen
pip install -e .

Quick Start

# Check if Cursor CLI is available
waygrounddocgen check

# Discover modules in a repository
waygrounddocgen discover /path/to/your/repo

# Generate documentation (discover + generate)
waygrounddocgen generate /path/to/your/repo

Usage

Discover Modules

Analyze a repository to identify its logical modules/components:

waygrounddocgen discover /path/to/repo
waygrounddocgen discover /path/to/repo --output modules.json

Output is a JSON file with discovered modules:

{
  "repo_path": "/path/to/repo",
  "language": "typescript",
  "framework": "express",
  "modules": [
    {
      "name": "auth",
      "path": "src/services/auth",
      "description": "Authentication and authorization service",
      "type": "service",
      "files": ["auth.service.ts", "auth.guard.ts"],
      "entry_points": ["AuthService", "authenticate"]
    }
  ]
}

Generate Documentation

Generate documentation for all discovered modules:

# Full pipeline (discover + generate)
waygrounddocgen generate /path/to/repo

# With custom parallelism
waygrounddocgen generate /path/to/repo --parallel 8

# From existing modules.json
waygrounddocgen generate /path/to/repo --modules modules.json

# Only specific modules
waygrounddocgen generate /path/to/repo --filter auth,users,payments

# Custom output directory
waygrounddocgen generate /path/to/repo --output ./docs/api

Options

Option	Short	Description
--modules	-m	Path to existing modules.json file
--output	-o	Output directory for documentation
--parallel	-p	Number of parallel Cursor tasks (default: 4)
--filter	-f	Comma-separated list of module names
--template	-t	Prompt template: generate_doc (default) or comprehensive
--quiet	-q	Suppress streaming output (hide Cursor's thinking)

Output Structure

docs/generated/
├── README.md           # Index of all modules
├── auth.md            # Auth module documentation
├── users.md           # Users module documentation
├── payments.md        # Payments module documentation
└── ...

Evaluate Documentation

Evaluate generated documentation against modules.json for quality assurance:

# Set API key for LLM evaluation (optional but recommended)
export ANTHROPIC_API_KEY=your_key

# Evaluate all modules
waygrounddocgen evaluate --modules modules.json --docs-dir docs/generated/

# Evaluate specific module
waygrounddocgen evaluate --modules modules.json --module "Authentication"

# With auto-retry on failure (regenerates docs up to 2 times)
waygrounddocgen evaluate --modules modules.json --docs-dir docs/generated/ --auto-retry

# Skip LLM evaluation (Phase 1 automated checks only)
waygrounddocgen evaluate --modules modules.json --docs-dir docs/generated/ --no-llm

# CI/CD mode (exit 1 on failure) with JSON report
waygrounddocgen evaluate --modules modules.json --docs-dir docs/generated/ --ci-mode --report report.json

Evaluation Phases

Phase 1: Automated Checks

• Coverage: Verifies documentation mentions expected elements (entry points, API endpoints, data structures)
• Structure: Validates required sections, code blocks, minimum word count
• Freshness: Checks if documentation is up-to-date with source code

Phase 2: LLM-as-Judge (requires anthropic package)

• Accuracy (1-5): Are facts correct? No hallucinations?
• Completeness (1-5): Is everything documented?
• Clarity (1-5): Is it understandable?

Example Workflow

# 1. Navigate to your repository
cd /path/to/your/project

# 2. Discover modules
waygrounddocgen discover . --output modules.json

# 3. Review discovered modules
cat modules.json | jq '.modules[].name'

# 4. Generate documentation
waygrounddocgen generate . --modules modules.json

# 5. View generated docs
open docs/generated/README.md

Troubleshooting

Cursor CLI not found

# Check if cursor is in PATH
which cursor

# If not, install from Cursor:
# Settings → General → Command Line → Install

No modules discovered

1. Check if the repository has a recognizable structure
2. Verify the prompts match your project patterns
3. Run discovery manually and review output

Parallel tasks timing out

Reduce parallelism or increase timeout:

# Use fewer parallel tasks
waygrounddocgen generate /path/to/repo --parallel 2

Development

Install for Development

git clone https://github.com/gauravmadan/waygrounddocgen.git
cd waygrounddocgen
pip install -e ".[dev]"

Build and Publish

# Build the package
python -m build

# Upload to PyPI
twine upload dist/*

License

MIT License - see LICENSE for details.