doc-writer

# doc-writer

Transform undocumented code into comprehensive, accurate documentation. doc-writer reads your source code, understands its behavior, and generates documentation in the format your project needs — from inline JSDoc comments to full OpenAPI 3.1 specifications.

## What It Does

doc-writer produces documentation at every level of granularity:

- **OpenAPI/Swagger specs**: Generate complete OpenAPI 3.1 specs from Express, FastAPI, gin, or Axum route handlers
- **JSDoc / TSDoc**: Inline documentation for TypeScript/JavaScript functions, classes, and interfaces
- **Rustdoc**: `///` doc comments for Rust functions, structs, traits, and modules
- **Python docstrings**: Google, NumPy, and Sphinx-style docstrings for Python functions and classes
- **README generation**: Project README with overview, installation, usage, API reference, configuration, and contributing sections
- **Architecture diagrams**: Mermaid.js diagrams for data flow, ER diagrams, service dependency graphs
- **Changelog generation**: CHANGELOG.md from conventional commit history
- **Migration guides**: Upgrade documentation comparing API versions

## Installation

```bash
anvil skill install doc-writer
```

## Usage

### Generate OpenAPI Spec from Express Router
```
/doc-writer openapi ./src/routes/
```

### Add JSDoc to a TypeScript File
```
/doc-writer jsdoc ./src/lib/crypto.ts
```

### Generate README for Current Project
```
/doc-writer readme
```

### Generate Architecture Diagram
```
/doc-writer diagram --type erd ./prisma/schema.prisma
```

### Generate Changelog from Git History
```
/doc-writer changelog --since v1.0.0
```

### Document a Python Module
```
/doc-writer docstring ./app/services/auth.py --style google
```

### Generate Full API Reference Site
```
/doc-writer site --output ./docs/api
```

## Supported Output Formats

| Doc Type | Formats |
|----------|---------|
| API Spec | OpenAPI 3.1, Swagger 2.0, RAML, AsyncAPI |
| Inline | JSDoc, TSDoc, Rustdoc, Google/NumPy/Sphinx docstrings |
| Diagrams | Mermaid.js, PlantUML, Graphviz DOT |
| Site | HTML (static), MkDocs, Docusaurus, VitePress |

## Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `--format` | Output format | auto-detect |
| `--output` | Output path | ./docs |
| `--style` | Docstring style (google, numpy, sphinx) | google |
| `--overwrite` | Overwrite existing docs | false |
| `--dry-run` | Preview without writing | false |
| `--include-private` | Document private/internal members | false |

## Requirements

- Source directory or specific files to document
- For OpenAPI generation: Express/Fastify/gin/Axum/FastAPI route handlers