# Story 10.28: Builder API Documentation

**Status:** Complete
**Priority:** Medium
**Depends on:** Stories 10.23-10.26 (Builder implementation)

---

## Context / Background

With the builder API complete and enforcement in place, comprehensive documentation is needed to make the API discoverable and usable. Good documentation will:

- Enable users to choose builder over Settings for most use cases
- Provide migration guidance from Settings-based configuration
- Show common patterns and combinations
- Serve as the primary reference for programmatic configuration

**Documentation scope:**

1. **API Reference** - Complete method reference
2. **User Guide** - Task-oriented tutorials
3. **Migration Guide** - Settings → Builder conversion
4. **Examples** - Real-world configuration patterns

---

## Scope (In / Out)

### In Scope

- Builder API reference documentation
- User guide for common configuration tasks
- Migration guide from Settings to Builder
- Example configurations for common deployments
- Update to main documentation index/navigation

### Out of Scope

- Settings class documentation (already exists)
- Environment variable documentation (already exists)
- Video tutorials or interactive content

---

## Acceptance Criteria

### AC1: API Reference Complete

**Description:** Every builder method is documented in the API reference.

**Validation:**
```markdown
# docs/api-reference/builder.md contains:
- Method signature for every public method
- Parameter descriptions with types
- Return type (always Self)
- Usage example for each method
- Equivalent Settings configuration
```

### AC2: User Guide Created

**Description:** Task-oriented guide helps users configure common scenarios.

**Validation:**
```markdown
# docs/user-guide/builder-configuration.md contains:
- Quick start (3-line example)
- Adding sinks (file, HTTP, cloud)
- Configuring filters (sampling, rate limiting)
- Setting up redaction
- Performance tuning
- Production checklist
```

### AC3: Migration Guide Created

**Description:** Users can convert existing Settings configurations to Builder.

**Validation:**
```markdown
# docs/guides/settings-to-builder-migration.md contains:
- Side-by-side comparison table
- Step-by-step conversion process
- Common patterns before/after
- When to use Settings vs Builder
```

### AC4: Example Configurations

**Description:** Real-world examples for common deployment scenarios.

**Validation:**
```markdown
# docs/examples/builder-configurations.md contains:
- Local development setup
- Production with CloudWatch
- Multi-sink with routing
- High-throughput with sampling
- Compliance-ready with redaction
```

### AC5: Navigation Updated

**Description:** Builder documentation is easily discoverable.

**Validation:**
- Builder API reference linked from main API docs
- User guide linked from main user guide index
- README mentions builder as primary configuration method

---

## Implementation Notes

### File Changes

```
docs/api-reference/builder.md (NEW)
docs/user-guide/builder-configuration.md (NEW)
docs/guides/settings-to-builder-migration.md (NEW)
docs/examples/builder-configurations.md (NEW)
docs/api-reference/index.md (MODIFIED - add builder link)
docs/user-guide/index.md (MODIFIED - add builder link)
README.md (MODIFIED - update configuration examples)
```

### API Reference Structure

```markdown
# Builder API Reference

## Overview

The `LoggerBuilder` provides a fluent API for configuring fapilog loggers.
All methods return `self` for chaining.

## Quick Start

\```python
from fapilog import LoggerBuilder

logger = (
    LoggerBuilder()
    .with_level("INFO")
    .add_stdout()
    .build()
)
\```

## Core Configuration

### with_level(level)
Set the minimum log level.

**Parameters:**
- `level` (str): Log level - "DEBUG", "INFO", "WARNING", "ERROR"

**Example:**
\```python
builder.with_level("INFO")
\```

**Equivalent Settings:**
\```python
Settings(core=CoreSettings(log_level="INFO"))
\```

### with_circuit_breaker(...)
Configure sink fault isolation.
...

## Sinks

### add_file(directory, ...)
Add rotating file sink.
...

### add_cloudwatch(log_group, ...)
Add AWS CloudWatch Logs sink.
...

## Filters

### with_sampling(rate, ...)
Configure probabilistic sampling.
...

## Complete Method Index

| Method | Category | Description |
|--------|----------|-------------|
| `with_level()` | Core | Set log level |
| `with_circuit_breaker()` | Core | Configure fault isolation |
| ... | ... | ... |
```

### User Guide Structure

```markdown
# Configuring Fapilog with the Builder API

## Why Use the Builder?

The builder API provides:
- **Discoverability** - IDE autocomplete shows all options
- **Validation** - Errors caught at build time
- **Readability** - Configuration intent is clear

## Quick Start

\```python
from fapilog import LoggerBuilder

# Minimal setup
logger = LoggerBuilder().add_stdout().build()

# Production setup
logger = (
    LoggerBuilder()
    .with_preset("production")
    .with_level("INFO")
    .add_file("logs/app", max_bytes="100 MB", max_files=10)
    .with_circuit_breaker(enabled=True)
    .build()
)
\```

## Common Tasks

### Adding Multiple Sinks
...

### Configuring Redaction
...

### Performance Tuning
...
```

### Migration Guide Structure

```markdown
# Migrating from Settings to Builder

## When to Migrate

Migrate to Builder when:
- Starting a new project
- Refactoring configuration
- Want better IDE support

Keep Settings when:
- Configuration is entirely env-var driven
- Using programmatic runtime changes
- Integrating with config management systems

## Conversion Table

| Settings Pattern | Builder Pattern |
|------------------|-----------------|
| `core=CoreSettings(log_level="INFO")` | `.with_level("INFO")` |
| `core=CoreSettings(sink_circuit_breaker_enabled=True)` | `.with_circuit_breaker(enabled=True)` |
| `sink_config=SinkConfig(cloudwatch=...)` | `.add_cloudwatch(...)` |

## Step-by-Step Migration

### Before
\```python
from fapilog import Settings, get_logger
from fapilog.core.settings import CoreSettings, CloudWatchSinkSettings

settings = Settings(
    core=CoreSettings(
        log_level="INFO",
        sinks=["cloudwatch"],
        sink_circuit_breaker_enabled=True,
    ),
    sink_config=Settings.SinkConfig(
        cloudwatch=CloudWatchSinkSettings(
            log_group_name="/myapp/prod",
            region="us-east-1",
        )
    )
)
logger = get_logger(settings=settings)
\```

### After
\```python
from fapilog import LoggerBuilder

logger = (
    LoggerBuilder()
    .with_level("INFO")
    .add_cloudwatch("/myapp/prod", region="us-east-1")
    .with_circuit_breaker(enabled=True)
    .build()
)
\```
```

---

## Tasks

### Phase 1: API Reference

- [ ] Create `docs/api-reference/builder.md`
- [ ] Document all core configuration methods
- [ ] Document all sink methods
- [ ] Document all filter/processor methods
- [ ] Document all advanced methods
- [ ] Add method index table

### Phase 2: User Guide

- [ ] Create `docs/user-guide/builder-configuration.md`
- [ ] Write quick start section
- [ ] Write common tasks sections
- [ ] Write production checklist

### Phase 3: Migration Guide

- [ ] Create `docs/guides/settings-to-builder-migration.md`
- [ ] Create conversion table
- [ ] Write step-by-step migration
- [ ] Document when to use each approach

### Phase 4: Examples

- [ ] Create `docs/examples/builder-configurations.md`
- [ ] Add local development example
- [ ] Add production CloudWatch example
- [ ] Add multi-sink routing example
- [ ] Add compliance example

### Phase 5: Navigation

- [ ] Update `docs/api-reference/index.md`
- [ ] Update `docs/user-guide/index.md`
- [ ] Update `README.md` examples
- [ ] Verify all links work

---

## Tests

### Documentation Tests

- All code examples compile (doctest or manual verification)
- All internal links resolve
- Navigation paths work

---

## Definition of Done

### Documentation Complete

- [ ] API reference covers all builder methods
- [ ] User guide covers common tasks
- [ ] Migration guide with before/after examples
- [ ] Real-world example configurations

### Quality Assurance

- [ ] Code examples tested
- [ ] Links verified
- [ ] Spell check passed

### Navigation

- [ ] Builder docs linked from main indexes
- [ ] README updated

---

## Risks / Rollback

### Risks

1. **Risk:** Documentation gets out of sync with code
   - **Mitigation:** Parity enforcement (10.27) catches changes

### Rollback Plan

Documentation is non-blocking; can be updated incrementally.

---

## Related Stories

- **Depends on:** Stories 10.23-10.26 (Builder implementation)
- **Related:** Story 10.27 - Builder API Parity Enforcement
- **Completes:** Builder API epic

---

## Code Review

**Date:** 2026-01-21
**Reviewer:** Claude
**Verdict:** OK to PR

### Summary

Documentation-only story implementing comprehensive Builder API documentation across 4 new files with navigation updates.

### AC Verification

| Criterion | Evidence |
|-----------|----------|
| AC1: API Reference | `docs/api-reference/builder.md` - 40+ methods with signatures, types, examples, Settings equivalents |
| AC2: User Guide | `docs/user-guide/builder-configuration.md` - Quick start, sinks, filters, redaction, performance |
| AC3: Migration Guide | `docs/guides/settings-to-builder-migration.md` - Conversion tables, 7 before/after examples |
| AC4: Examples | `docs/examples/builder-configurations.md` - 12 real-world patterns |
| AC5: Navigation | `docs/api-reference/index.md`, `docs/user-guide/index.md`, `README.md` updated |

### Quality Gates

- [x] Documentation complete
- [x] Code examples follow project patterns
- [x] Navigation links verified
- [x] No code changes requiring tests

---

## Change Log

| Date | Change | Author |
|------|--------|--------|
| 2026-01-20 | Initial draft | Claude |
| 2026-01-21 | Implementation complete, code review passed | Claude |
