Consider hybrid documentation strategy: rustdoc + auto-generated CLI reference + mdBook

[joshrotenberg]

Problem

As the project grows (101 markdown files, ~9,600 lines), there's a risk of documentation drifting from code. We currently have:

• mdBook for all documentation (narrative + reference)
• Minimal rustdoc usage
• No auto-generation from code

Proposed Solution

Adopt a hybrid approach similar to rust-analyzer:

1. Use Rustdoc for API Reference

• Document all library crates (redis-cloud, redis-enterprise, redisctl-config)
• Handler modules and request/response types
• Published automatically to docs.rs
• Examples tested via cargo test --doc

Benefits: Always in sync, compiler-checked, intra-doc links

2. Auto-Generate CLI Reference

Create cargo xtask generate-docs to extract CLI documentation from clap:

// Generate from actual Cli struct
let app = redisctl::Cli::command();
let help = app.render_help();
// Write to docs/src/reference/cli_generated.md

Include in mdBook via {{#include cli_generated.md}}

Benefits: Single source of truth (cli.rs), always matches actual commands

3. Keep mdBook for Narrative Docs

Use mdBook only for:

• Getting Started guides
• Tutorials and walkthroughs
• How-to guides
• Architecture/design decisions

Remove from mdBook:

• Detailed API schemas (→ rustdoc)
• CLI syntax details (→ auto-generated)

4. Cross-Link Between Systems

• mdBook → rustdoc: Link to docs.rs for API details
• rustdoc → mdBook: Link to guides for workflows
• Use mdbook-rustdoc-link for better integration

Implementation Phases

Phase 1: Foundation

• Add comprehensive rustdoc to all public APIs
• Add #![doc = include_str!("../README.md")] to each crate
• Add doc examples that are tested

Phase 2: Auto-Generation (like rust-analyzer)

• Create xtask generate-docs command
• Generate CLI reference from clap definitions
• Generate endpoint lists from handler modules
• Include generated files in mdBook
• Add CI check for stale generated files

Phase 3: Reorganize

• Remove API reference details from mdBook (point to rustdoc)
• Remove detailed CLI syntax (use generated)
• Keep only narrative/tutorial content
• Add cross-links

Phase 4: Polish

• Add mdbook-rustdoc-link preprocessor
• Publish rustdoc to GitHub Pages alongside mdBook
• Add rustdoc generation to CI/CD

Examples

rust-analyzer generates 4 sections dynamically:

• Assists, Configuration, Diagnostics, Features
• All from actual code via cargo test and cargo xtask codegen

For redisctl, we could generate:

• CLI Commands (from clap)
• Cloud API Endpoints (from handlers)
• Enterprise API Endpoints (from handlers)
• Configuration Options (from config structs)

Benefits

1. Reduced maintenance - Docs auto-update with code
2. Always accurate - Generated from source of truth
3. Better discoverability - API docs on docs.rs
4. Tested examples - Doc examples run in cargo test
5. Cleaner mdBook - Focused on narrative/guides

Related

• rust-analyzer: https://github.com/rust-lang/rust-analyzer/blob/master/docs/book/README.md
• mdbook-rustdoc-link: https://lib.rs/crates/mdbook-rustdoc-link
• #![doc = include_str!()] pattern: https://linebender.org/blog/doc-include/