Add Comprehensive Documentation

Problem

The tool lacks user-facing documentation:

• No rustdoc for public APIs
• No usage examples
• No troubleshooting guide
• Internal architecture not fully documented

Proposed Documentation Structure

3.1 Rustdoc for Library Code

Add module-level documentation and doc comments for all public items:

• Module-level docs for all modules in src/
• Document all public structs, enums, traits
• Document all public functions with examples
• Configure cargo doc to fail on missing docs

3.2 User Guide (docs/user-guide/)

docs/user-guide/01-installation.md

• Installation via cargo install
• Installation via nix
• Building from source
• Updating

docs/user-guide/02-getting-started.md

• Basic usage
• Common workflows
• Environment variables
• Configuration

docs/user-guide/03-commands.md

• Detailed explanation of each command
• Examples for each command
• Common options explained

docs/user-guide/04-ci-integration.md

• Using with GitHub Actions
• Using with Prow
• Environment variable reference
• Troubleshooting CI issues

docs/user-guide/05-publishing.md

• Publishing to Cargo registries
• Publishing to npm
• Publishing Docker images
• Publishing binaries to GitHub releases
• Publishing to S3

docs/user-guide/06-testing.md

• Running tests in monorepo
• Test isolation and databases
• Parallel test execution
• Custom test configurations

docs/user-guide/07-troubleshooting.md

• Common errors and solutions
• Debug mode and logging
• Known issues

3.3 Architecture Documentation (docs/architecture/)

docs/architecture/01-overview.md

• System design
• Core concepts
• Data flow

docs/architecture/02-crate-graph.md

• How dependency graphs are built
• Change detection algorithm
• Performance considerations

docs/architecture/03-publishing-flow.md

• Publish decision logic
• Registry integrations
• Failure handling

docs/architecture/04-parallelism.md

• Concurrency model
• Job limits and semaphores
• Resource management

3.4 Examples (examples/)

Create runnable examples showing:

• Basic usage of CrateGraph programmatically
• Custom publishing targets
• Advanced workflows

Implementation Plan

Phase 1: Critical Rustdoc (Week 1)

• Add module-level docs for all modules in src/
• Document all public structs, enums, traits
• Document all public functions
• Add examples in doc comments
• Configure cargo doc to fail on missing docs

Phase 2: User Guide (Week 2-3)

• Write installation guide
• Write getting started guide
• Document all commands with examples
• Write CI integration guide
• Create troubleshooting guide

Phase 3: Architecture Docs (Week 4)

• Document system architecture
• Explain CrateGraph internals
• Document publishing flow
• Document parallelism model

Phase 4: Examples (Week 5)

• Create runnable examples
• Add examples to CI to ensure they stay working
• Link examples from user guide

Success Metrics

• 100% of public APIs have rustdoc
• cargo doc passes with --deny warnings
• User guide covers all commands
• At least 3 runnable examples
• Documentation site generated and published

Tools

• Use rustdoc for API docs
• Use mdbook for user guide and architecture docs
• Host on GitHub Pages or docs.rs

Labels

documentation, priority:medium

Start by inventorying public items under src/ and reviewing the proposed docs/user-guide/, docs/architecture/, and examples/ structure. Run cargo doc --deny warnings and inspect the command surface, publishing flow, and architecture before dividing the work. Done means public APIs are documented, the user and architecture guides cover the listed topics, and at least three runnable examples are included.