doc-generate

name	doc-generate
description	Generate documentation from specs, code comments, and type definitions. Creates professional docs from SEA-Forge source.

Documentation Generation

Use this skill when:

• Generating documentation from specs
• Creating API documentation from types
• Generating reference docs from code comments
• Updating project documentation

Documentation Sources

1. From Specs

Generate documentation from SEA specs:

# Find spec files
find docs/specs -name "*.md" -type f

# Extract spec metadata
for spec in docs/specs/**/*.md; do
  # Extract frontmatter
  # Extract sections
  # Generate documentation
done

2. From Code Comments

Extract JSDoc/TSDoc comments:

/**
 * User entity in the SEA-Forge system.
 *
 * @remarks
 * Users are the core entity representing human participants
 * in the organization compilation process.
 *
 * @example
 * ```typescript
 * const user = new User({
 *   id: "123",
 *   name: "John Doe",
 *   email: "[e-mail]"
 * });
 * ```
 */
export class User {
  // ...
}

3. From Type Definitions

Generate documentation from TypeScript types:

/**
 * User preferences configuration
 */
export interface UserPreferences {
  /** User's theme preference */
  theme: 'light' | 'dark' | 'auto';

  /** Notification settings */
  notifications: {
    /** Email notifications enabled */
    email: boolean;

    /** Push notifications enabled */
    push: boolean;
  };

  /** Display density */
  density: 'compact' | 'comfortable' | 'spacious';
}

Generation Templates

API Reference Template

# API Reference: {module}

## Overview
{description from module comments}

## Classes

### {ClassName}

{description from class comments}

#### Constructor
```typescript
constructor(options: {Options})

{description}

Methods

{methodName}

{methodSignature}

{description}

Parameters:

• {param}: {description}

Returns: {return type and description}

Throws: {exceptions}

Example:

{example code}

Interfaces

{InterfaceName}

{description}

Properties

• {property}: {type} - {description}

Types

{TypeName}

{description}

### Spec Documentation Template

```markdown
# {Spec Title}

**Version:** {version}
**Status:** {status}
**Author:** {author}

## Overview
{from Context section}

## Requirements
{from Requirements section}

### Functional Requirements
{list of functional requirements}

### Non-Functional Requirements
{list of non-functional requirements}

## Design
{from Design section}

### Architecture
{architecture overview}

### API Surface
{API contracts}

### Data Model
{data structures}

## Implementation Notes
{from Implementation section}

## Related Specs
- [Related Spec 1](path/to/spec1.md)
- [Related Spec 2](path/to/spec2.md)

Generation Process

Step 1: Extract Documentation

# Use TypeDoc to extract JSDoc
npx typedoc --out tmp/typedoc src/

# Extract from specs
python3 tools/extract_specs.py docs/specs/ > tmp/specs.json

# Extract types
npx ts-json-schema-generator --path src/types/ --out tmp/types.json

Step 2: Transform to Markdown

Convert extracted data to markdown documentation:

// tools/doc_generator.ts
import { extractJSDoc } from './extractors/jsdoc';
import { extractSpecs } from './extractors/specs';
import { renderMarkdown } from './renderers/markdown';

const docs = {
  api: extractJSDoc('src/'),
  specs: extractSpecs('docs/specs/'),
  types: extractTypes('src/types/')
};

const markdown = renderMarkdown(docs);
await writeFile('docs/reference/api.md', markdown.api);
await writeFile('docs/reference/specs.md', markdown.specs);

Step 3: Validate Documentation

Check generated documentation:

# Check all links resolve
npx markdown-link-check docs/reference/api.md

# Check markdown formatting
npx prettier --check docs/reference/**/*.md

# Build docs site (if using Docusaurus, etc.)
npm run docs:build

Documentation Types

API Reference

Generated from code comments and type definitions.

Architecture Docs

Generated from specs and design documents.

User Guides

Generated from usage examples and comments.

Contributing Guide

Generated from development patterns and workflows.

Output Locations

docs/
├── reference/
│   ├── api.md           # API reference
│   ├── types.md         # Type definitions
│   ├── specs.md         # Spec documentation
│   └── architecture.md  # Architecture docs
├── guides/
│   ├── getting-started.md
│   └── tutorials/
└── site/                # Generated doc site

Custom Documentation Templates

Create custom templates in .claude/templates/docs/:

<!-- .claude/templates/docs/api-page.hbs -->
# {{class.name}}

{{class.description}}

## Constructor
```typescript
constructor({{class.constructorParams}})

{{#each class.methods}}

{{this.name}}

{{this.signature}}

{{this.description}}

{{#if this.deprecated}}

⚠️ Deprecated: {{this.deprecationMessage}} {{/if}}

{{/each}}

## Generation Commands

```bash
# Generate all documentation
just docs

# Generate API reference only
just docs:api

# Generate spec documentation
just docs:specs

# Generate and serve docs locally
just docs:serve

# Validate documentation
just docs:check

Integration

• Integrates with docx skill for Word docs
• Integrates with custom-doc-templates for custom formats
• Integrates with Docusaurus/MkDocs for doc sites

Usage

Claude invokes when:

• User asks "generate documentation"
• After code changes that affect API
• Before releases
• User asks "update docs"

Output

After generation, output:

## Documentation Generated

**Output:** {path/to/docs}
**Files generated:** {count}
**APIs documented:** {count}
**Specs documented:** {count}

### Generated Files
- {file1}
- {file2}
- {file3}

### Validation
- Links: ✅/❌
- Formatting: ✅/❌
- Completeness: ✅/❌

### Next Steps
1. Review generated documentation
2. Add custom content if needed
3. Commit documentation changes