# Story 10.15: Documentation Correctness and CI Enforcement

**Status:** Complete
**Priority:** High
**Depends on:** None

---

## Context / Background

An external audit identified documentation accuracy as the highest-ROI improvement for the project. Three specific issues were found:

1. **Environment variable mismatch**: `docs/user-guide/configuration.md:146` documents `FAPILOG_FILE__DIRECTORY` and `FAPILOG_FILE__MAX_BYTES`, but the actual env vars are `FAPILOG_SINK_CONFIG__ROTATING_FILE__DIRECTORY` etc. No short aliases exist for the rotating file sink.

2. **Architecture docs drift**: `docs/architecture/high-level-architecture.md` describes a source tree that doesn't match reality:
   - Doc shows `src/fapilog/integrations/fastapi/` but actual is `src/fapilog/fastapi/`
   - Doc shows `src/fapilog/runtime/{loader,compatibility,extras}.py` but actual is `src/fapilog/plugins/loader.py` with no `compatibility.py` or `extras.py`
   - Doc references `CompatibilityManager` and `ExtrasResolver` components that don't exist

3. **No CI protection**: `.readthedocs.yml:19` sets `fail_on_warning: false`, allowing documentation drift to go unnoticed.

These issues break onboarding and damage trust. Documentation quality (weight 14) and DX (weight 16) are large score factors in the audit.

---

## Scope (In / Out)

### In Scope

- Fix env var names in `docs/user-guide/configuration.md`
- Update architecture docs to match actual source tree
- Enable `fail_on_warning: true` in ReadTheDocs
- Add CI step to validate docs build without warnings
- Add short env aliases for rotating file sink (optional, if straightforward)

### Out of Scope

- Comprehensive documentation rewrite (future story)
- Automated doc generation from code (future story)
- Documentation testing framework (future story)

---

## Acceptance Criteria

### AC1: Env Var Documentation Matches Reality

**Description:** All environment variable names in user-facing docs must match the actual env vars supported by the codebase.

**Validation:**
```bash
# Extract documented env vars and verify against generated matrix
grep -E "FAPILOG_[A-Z_]+" docs/user-guide/configuration.md | \
  while read var; do
    grep -q "$var" docs/env-vars.md || echo "MISMATCH: $var"
  done
# Should output nothing (no mismatches)
```

### AC2: Architecture Docs Match Source Tree

**Description:** The source tree diagram in `docs/architecture/high-level-architecture.md` accurately reflects `src/fapilog/` structure.

**Validation:**
```bash
# Key paths mentioned in docs should exist
test -d src/fapilog/fastapi && echo "OK: fastapi dir exists"
test -f src/fapilog/plugins/loader.py && echo "OK: loader.py exists"
# Paths that shouldn't be referenced
test ! -d src/fapilog/integrations && echo "OK: no integrations dir"
test ! -d src/fapilog/runtime && echo "OK: no runtime dir"
```

### AC3: ReadTheDocs Fails on Warnings

**Description:** Documentation builds must fail when Sphinx emits warnings, preventing drift.

**Validation:**
```yaml
# .readthedocs.yml should contain:
sphinx:
  fail_on_warning: true
```

### AC4: CI Validates Docs Build

**Description:** CI pipeline includes a step that builds docs and fails on warnings.

**Validation:**
```bash
# This command should be in CI and exit non-zero on warnings
sphinx-build -W -b html docs/ docs/_build/html
```

---

## Implementation Notes

### File Changes

```
docs/user-guide/configuration.md (MODIFIED - fix env var names)
docs/architecture/high-level-architecture.md (MODIFIED - update source tree)
.readthedocs.yml (MODIFIED - enable fail_on_warning)
.github/workflows/ci.yml (MODIFIED - add docs validation step)
```

### Env Var Fixes

Replace in `docs/user-guide/configuration.md`:
```bash
# Before
export FAPILOG_FILE__DIRECTORY=/var/log/myapp
export FAPILOG_FILE__MAX_BYTES="10 MB"
export FAPILOG_FILE__INTERVAL_SECONDS="daily"

# After
export FAPILOG_SINK_CONFIG__ROTATING_FILE__DIRECTORY=/var/log/myapp
export FAPILOG_SINK_CONFIG__ROTATING_FILE__MAX_BYTES="10 MB"
export FAPILOG_SINK_CONFIG__ROTATING_FILE__INTERVAL_SECONDS="daily"
```

---

## Tasks

### Phase 1: Fix Documentation

- [ ] Update env var names in `docs/user-guide/configuration.md`
- [ ] Update source tree diagram in `docs/architecture/high-level-architecture.md`
- [ ] Remove references to non-existent components (CompatibilityManager, ExtrasResolver)
- [ ] Update FastAPI integration paths in architecture docs

### Phase 2: Enable CI Protection

- [ ] Set `fail_on_warning: true` in `.readthedocs.yml`
- [ ] Add docs build step to CI workflow
- [ ] Fix any existing Sphinx warnings that surface

### Phase 3: Verification

- [ ] Run local docs build with `-W` flag
- [ ] Verify ReadTheDocs build passes
- [ ] Update CHANGELOG

---

## Tests

### Manual Verification

- Build docs locally: `sphinx-build -W -b html docs/ docs/_build/html`
- Verify no warnings are emitted
- Check ReadTheDocs build status after merge

### CI Integration

- CI should fail if docs build produces warnings
- CI should pass after fixes are applied

---

## Definition of Done

### Code Complete

- [ ] All env var references corrected
- [ ] Architecture docs match source tree
- [ ] No references to non-existent components

### Quality Assurance

- [ ] `sphinx-build -W` passes locally
- [ ] ReadTheDocs build passes with `fail_on_warning: true`
- [ ] CI docs step passes

### Documentation

- [ ] CHANGELOG updated with documentation fixes
- [ ] No new Sphinx warnings introduced

---

## Risks / Rollback

### Risks

1. **Risk:** Enabling `fail_on_warning` reveals many existing warnings
   - **Mitigation:** Fix warnings incrementally; can use warning suppression for known issues while fixing

2. **Risk:** Short env var aliases may require code changes
   - **Mitigation:** Document full paths first; aliases are optional enhancement

### Rollback Plan

If issues occur:
1. Revert `fail_on_warning` to `false` if blocking releases
2. Documentation fixes are low-risk and don't affect runtime

---

## Related Stories

- **Related:** Story 10.14 - Extras documentation accuracy (similar area)
- **Related:** Story 10.9 - DX documentation migration guide

---

## Code Review

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

### Summary

Documentation accuracy fixes and CI enforcement. Corrected env var names, updated architecture diagrams to match actual source tree, enabled fail_on_warning in ReadTheDocs, added docs build job to CI.

### AC Verification

| Criterion | Evidence |
|-----------|----------|
| AC1: Env Var Documentation Matches Reality | `docs/user-guide/configuration.md:146-148` - Changed `FAPILOG_FILE__*` → `FAPILOG_SINK_CONFIG__ROTATING_FILE__*` |
| AC2: Architecture Docs Match Source Tree | `docs/architecture/high-level-architecture.md:281-310` - Updated diagram verified against filesystem |
| AC3: ReadTheDocs Fails on Warnings | `.readthedocs.yml:19` - `fail_on_warning: true` |
| AC4: CI Validates Docs Build | `.github/workflows/ci.yml:218-237` - `sphinx-build -W` job added |

### Quality Gates

- [x] sphinx-build -W passed
- [x] No weak assertions (N/A - docs only)
- [x] No dead code (N/A - docs only)

---

## Change Log

| Date | Change | Author |
|------|--------|--------|
| 2026-01-18 | Initial draft from audit findings | Claude |
| 2026-01-18 | Implementation complete, code review passed | Claude |
