/docs-generate

description: Generate documentation from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications.

Generate Documentation from Code

Generate documentation automatically from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications. Creates comprehensive API docs, type references, and usage examples.

Usage

/docs:generate <source-type> <path> [options]

Source Types

1. TypeScript/JavaScript Code

/docs:docs-generate code ./src \
  --output ./docs/api \
  --format markdown

2. OpenAPI/Swagger Specs

/docs:docs-generate openapi ./api/openapi.yaml \
  --output ./docs/api \
  --interactive

3. GraphQL Schema

/docs:docs-generate graphql ./schema.graphql \
  --output ./docs/graphql

4. SpecWeave Living Docs

/docs:docs-generate specweave ./.specweave/docs \
  --output ./docs/specs \
  --include features,modules,architecture

Options

General Options

• `--output <path>` - Output directory (default: `./docs/generated`)
• `--format <format>` - Output format: markdown, html, json (default: markdown)
• `--template <template>` - Custom template directory
• `--watch` - Watch for changes and regenerate

Code Documentation Options

• `--exclude <patterns>` - Exclude files/directories (glob patterns)
• `--include-private` - Include private members (default: false)
• `--include-internal` - Include @internal tagged members (default: false)
• `--examples` - Generate usage examples (default: true)
• `--types` - Generate type reference docs (default: true)

OpenAPI Options

• `--interactive` - Generate interactive API playground (default: true)
• `--group-by <field>` - Group endpoints by: tag, path, method (default: tag)
• `--show-examples` - Include request/response examples (default: true)

SpecWeave Options

• `--include <types>` - Comma-separated: features, modules, architecture, team
• `--depth <number>` - Directory depth to traverse (default: unlimited)
• `--format-adrs` - Special formatting for ADRs (default: true)

Generated Documentation

From TypeScript Code

Generates comprehensive API documentation using TypeDoc:

**Input**: TypeScript source files

/**
 * User management service
 * @category Services
 * @example
 * ```ts
 * const service = new UserService();
 * const user = await service.getUser(123);
 * ```
 */
export class UserService {
  /**
   * Retrieve user by ID
   * @param userId - Unique user identifier
   * @returns User object or null if not found
   * @throws {UserNotFoundError} If user doesn't exist
   */
  async getUser(userId: number): Promise<User | null> {
    // implementation
  }
}

**Output**: Markdown documentation

# UserService

User management service

## Methods

### getUser

Retrieve user by ID

**Parameters:**
- `userId`: number - Unique user identifier

**Returns:** `Promise<User | null>` - User object or null if not found

**Throws:**
- `UserNotFoundError` - If user doesn't exist

**Example:**
\```typescript
const service = new UserService();
const user = await service.getUser(123);
\```

From OpenAPI Specification

Generates interactive API documentation:

**Input**: OpenAPI YAML/JSON

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

**Output**: Interactive Markdown with API playground

# GET /users/{id}

Get user by ID

## Parameters

| Name | In   | Type    | Required | Description |
|------|------|---------|----------|-------------|
| id   | path | integer | Yes      | User ID     |

## Responses

### 200 OK

Successful response

**Response Schema:**
\```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}
\```

## Try it out

[Interactive API Playground]

\```bash
curl -X GET https://api.example.com/users/123 \
  -H "Authorization: Bearer YOUR_TOKEN"
\```

From SpecWeave Living Docs

Generates consolidated documentation from `.specweave/docs/`:

**Input**: SpecWeave directory structure

.specweave/docs/
├── features/
│   ├── FS-001/
│   │   ├── feature.md
│   │   └── user-stories/
│   │       ├── US-001.md
│   │       └── US-002.md
│   └── FS-002/
├── modules/
│   ├── authentication/
│   │   └── module.md
│   └── payments/
└── architecture/
    ├── adr/
    │   ├── 0001-tech-stack.md
    │   └── 0002-database-choice.md
    └── diagrams/

**Output**: Organized Docusaurus docs

docs/
├── features/
│   ├── fs-001-user-authentication.md
│   ├── fs-002-payment-processing.md
│   └── index.md
├── modules/
│   ├── authentication.md
│   ├── payments.md
│   └── index.md
└── architecture/
    ├── decisions/
    │   ├── adr-0001.md
    │   ├── adr-0002.md
    │   └── index.md
    └── diagrams.md

Configuration

TypeDoc Configuration

Create `typedoc.json`:

{
  "entryPoints": ["./src"],
  "out": "./docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "excludePrivate": true,
  "excludeInternal": true,
  "categorizeByGroup": true,
  "categoryOrder": ["Services", "Models", "Utils", "*"],
  "sort": ["source-order"]
}

Custom Templates

Create custom Handlebars templates:

{{!-- templates/class.hbs --}}
# {{name}}

{{#if comment}}
{{comment}}
{{/if}}

## Constructor

\```typescript
new {{name}}({{#each constructorParams}}{{name}}: {{type}}{{#unless @last}}, {{/unless}}{{/each}})
\```

## Methods

{{#each methods}}
### {{name}}

{{comment}}

**Signature:**
\```typescript
{{signature}}
\```
{{/each}}

Continuous Documentation

Watch Mode

Auto-regenerate on file changes:

/docs:docs-generate code ./src --watc