/laravel-agent:docs:generate

Overview

The /docs:generate command analyzes your Laravel codebase and automatically generates comprehensive, well-structured documentation. It scans your directory structure, reads key files, extracts PHPDoc comments, and identifies patterns to create professional documentation tailored to your project.

Usage

/laravel-agent:docs:generate [type] [target]

Examples

# Generate README and basic documentation
/laravel-agent:docs:generate

# Generate API documentation
/laravel-agent:docs:generate api

# Generate architecture overview
/laravel-agent:docs:generate architecture

# Document a specific directory
/laravel-agent:docs:generate app/Services

# Generate model documentation
/laravel-agent:docs:generate models

Documentation Types

The command supports several documentation types, each tailored to specific needs:

Documentation Process

The command follows a systematic approach to generate accurate documentation:

1. Codebase Analysis

• Scans directory structure to understand project organization
• Reads key configuration and source files
• Identifies design patterns and architectural choices
• Extracts PHPDoc comments and type hints

2. Documentation Generation

Creates well-structured markdown documentation based on analysis:

## Project Documentation

### Overview
<Generated description based on code analysis>

### Features
- Feature 1: <description>
- Feature 2: <description>

### Installation
```bash
composer install
php artisan migrate
```

### Architecture
```
app/
├── Features/     # Self-contained business features
├── Modules/      # Reusable domain logic
├── Services/     # Business logic services
└── Actions/      # Single-purpose actions
```

### Models
| Model | Table | Relationships |
|-------|-------|---------------|
| User | users | hasMany(Order) |
| Order | orders | belongsTo(User), hasMany(OrderItem) |
```

3. Output Options

Documentation can be generated in multiple formats:

• Markdown files - Individual .md files for each section
• README.md - Single comprehensive project overview
• docs/ directory - Organized documentation structure
• Docusaurus/VitePress compatible - Static site generator ready

Generated Files

The command creates a comprehensive documentation structure:

docs/
├── README.md           # Project overview and introduction
├── ARCHITECTURE.md     # System design and patterns
├── API.md              # API reference and endpoints
├── MODELS.md           # Database models and relationships
└── DEPLOYMENT.md       # Deployment and configuration guide

Interactive Mode

When run without arguments, the command provides interactive prompts:

1. Documentation Type

• README (project overview)
• API reference
• Architecture overview
• Model documentation
• All of the above

2. Target Scope

• Entire project
• Specific directory (select from list)
• Specific feature/module

3. Output Format

• Markdown files (individual documents)
• Single README.md (all-in-one)
• Docusaurus compatible (with frontmatter)
• VitePress compatible (with config)

4. Diagram Generation

• Yes - Include Mermaid diagrams for architecture and relationships
• No - Text-only documentation

Example Output

After successful generation, you'll receive a comprehensive report:

## Documentation Generated

### Files Created
| File | Type | Description |
|------|------|-------------|
| docs/README.md | Overview | Project introduction and setup |
| docs/API.md | Reference | API endpoints documentation |
| docs/ARCHITECTURE.md | Design | System architecture overview |

### Statistics
- Models documented: 15
- API endpoints: 32
- Services: 8
- Actions: 12

### Next Steps
1. Review generated documentation
2. Add custom sections as needed
3. Configure static site generator (optional)

Generated Architecture Documentation Example

# Architecture Overview

## Directory Structure

```
app/
├── Features/          # Self-contained business features
│   ├── Orders/       # Order management feature
│   └── Payments/     # Payment processing feature
├── Modules/          # Reusable domain logic
│   ├── Inventory/    # Inventory management
│   └── Shipping/     # Shipping calculations
├── Services/         # Business logic services
│   └── PaymentService.php
└── Actions/          # Single-purpose actions
    └── CreateOrderAction.php
```

## Design Patterns

### Repository Pattern
Used for data access abstraction in payment processing.

### Service Layer
Business logic encapsulated in dedicated service classes.

### Action Pattern
Single-responsibility actions for complex operations.

## Component Interactions

```mermaid
graph TD
    A[Controller] -->|uses| B[Service]
    B -->|calls| C[Action]
    C -->|accesses| D[Repository]
    D -->|queries| E[Model]
```

Generated Model Documentation Example

# Database Models

## User Model

**Table:** `users`

### Attributes
- `id` - Primary key
- `name` - string(255)
- `email` - string(255), unique
- `email_verified_at` - timestamp, nullable
- `password` - string(255)

### Relationships
- `hasMany(Order)` - User's orders
- `hasMany(Payment)` - User's payments
- `belongsToMany(Role)` - User roles

### Scopes
- `active()` - Returns only active users
- `verified()` - Returns only verified users

### Methods
- `isAdmin()` - Check if user has admin role
- `getTotalSpent()` - Calculate total amount spent

Generated API Documentation Example

# API Documentation

## Authentication
All endpoints require Bearer token authentication.

```bash
Authorization: Bearer {token}
```

## Endpoints

### Products

#### GET /api/v1/products
List all products with pagination.

**Query Parameters:**
- `filter[name]` - Filter by product name
- `filter[category]` - Filter by category
- `sort` - Sort by field (name, price, created_at)
- `page` - Page number

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Product Name",
      "price": 99.99,
      "category": "Electronics"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 100
  }
}
```

#### POST /api/v1/products
Create a new product.

**Request Body:**
```json
{
  "name": "Product Name",
  "price": 99.99,
  "category_id": 1
}
```

Best Practices

1. Keep documentation current - Re-run the command after major changes
2. Use PHPDoc comments - The command extracts information from docblocks
3. Organize your code - Clear structure leads to better documentation
4. Review and customize - Generated docs are a starting point; add your insights
5. Include diagrams - Visual representations help understanding complex systems
6. Document the "why" - The command captures the "what"; add the "why" manually

Use Cases

• Onboarding new developers - Comprehensive overview of the codebase
• Project handoffs - Complete documentation for client delivery
• API client development - Clear endpoint documentation for frontend teams
• Code reviews - Architecture documentation for review preparation
• Technical debt assessment - Understanding current system structure

Allowed Tools

This command has access to the following tools for analysis and generation:

• Task - Breaking down complex documentation tasks
• Read - Reading source files for analysis
• Glob - Finding files matching patterns
• Grep - Searching code for specific patterns
• Bash - Running Laravel artisan commands for insights
• Write - Creating new documentation files
• Edit - Updating existing documentation

See Also

• /laravel-agent:api:docs - Generate OpenAPI/Swagger documentation
• /laravel-agent:refactor:analyze - Analyze code for refactoring opportunities