Add Comprehensive Documentation

[loispostula]

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