Skip to content

Automated Documentation with mdBook

This guide shows you how to set up automated, always-up-to-date documentation for any project using Prodigy's book workflow system. This same system maintains the documentation you're reading right now.

Overview

The book workflow system: - Analyzes your codebase to build a feature inventory - Detects documentation drift by comparing docs to implementation - Updates documentation automatically using Claude - Maintains consistency across all chapters - Runs on any project - just configure and go

The generalized commands work for any codebase: Rust, Python, JavaScript, etc.

Why Automated Documentation?

The Problem: Documentation drifts out of sync with code. New features get added, APIs change, examples break, and manually updating docs is time-consuming and error-prone.

The Solution: This workflow system solves documentation drift by:

  • Always up-to-date - Automatically detects when docs don't match implementation
  • Code-grounded examples - All examples extracted from actual source code with file references
  • Parallel processing - MapReduce architecture processes chapters concurrently
  • Quality guaranteed - Validation ensures 100% completeness before accepting updates
  • Version controlled - All changes tracked via git commits with full audit trail
  • CI/CD ready - Runs in GitHub Actions or any CI system

Real Results: This documentation you're reading right now is maintained by this system. Every code example references actual source files. When Prodigy's features change, the docs update automatically.

Quick Start

Ready to get started? Here's the fastest path:

  1. Install Prodigy - Prodigy, Claude Code CLI, Rust
  2. Follow the Quick Start guide - 15-20 minute setup for automated docs
  3. Or dive deeper with the Tutorial - 30 minute comprehensive walkthrough

Choose your path based on your time and experience level

How It Works

The documentation workflow uses a MapReduce pattern to process your codebase in parallel:

Workflow Phases

  1. Setup Phase (Feature Analysis):
  2. Analyzes your codebase to build a complete feature inventory
  3. Detects documentation gaps by comparing existing docs to implementation
  4. Creates missing chapter/subsection files with placeholders
  5. Generates work items for the map phase

  6. Source: workflows/book-docs-drift.yml:24-34

  7. Map Phase (Parallel Processing):

  8. Processes each chapter/subsection in parallel using isolated git worktrees
  9. For each documentation item:
    • Analyzes drift between documentation and implementation
    • Fixes identified issues with real code examples
    • Validates fixes meet quality standards
  10. Runs up to 3 items concurrently (configurable via MAX_PARALLEL)
  11. Failed items go to Dead Letter Queue (DLQ) for retry

  12. Source: workflows/book-docs-drift.yml:37-59

  13. Reduce Phase (Validation):

  14. Rebuilds the entire book to ensure chapters compile together
  15. Checks for broken links between chapters
  16. Fixes any build errors discovered during compilation
  17. Cleans up temporary analysis files

  18. Source: workflows/book-docs-drift.yml:62-82

  19. Merge Phase (Integration):

  20. Merges updated documentation back to your original branch
  21. Preserves your working tree state
  22. Uses Claude to handle any merge conflicts
  23. Source: workflows/book-docs-drift.yml:93-100

Worktree Isolation

All phases execute in an isolated git worktree: - Your main repository remains untouched during execution - Each map agent runs in its own child worktree - Changes merge back only after successful completion - Failed workflows don't pollute your working directory - Learn more: Understanding the Workflow

Quality Guarantees

The workflow ensures documentation quality through: - Code-grounded examples: All examples extracted from actual implementation - Validation checkpoints: Each fix validated before proceeding - Build verification: Full book rebuild ensures no broken references - Source attribution: Examples include file paths and line numbers - Automatic retry: Failed items can be retried via prodigy dlq retry

For detailed information about each phase, see the subsections below.

Additional Topics

Getting Started

Understanding the System

Advanced Usage

Reference