docs: a rustdoc-based documentation system

[Kilerd]

Four changes that together make the generated documentation the real one.

1. docs.rs was showing half the framework

There was no [package.metadata.docs.rs], so docs.rs builds with default features only — which is just http1. That means #[api], Schematic, Operable, ParameterProvider and the entire OpenAPI layer never appeared on docs.rs at all: the framework's headline capability was invisible to anyone reading the published docs.

All three crates now declare:

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

2. Feature-gated items say which feature they need

Building with all features would otherwise imply everything is unconditionally available. #[cfg_attr(docsrs, doc(cfg(feature = "...")))] puts a "requires feature X" badge on each gated item. Nightly-only, so it applies on docs.rs and is skipped elsewhere.

3. #![deny(missing_docs)] — and the 64 items that needed it

Every public item across gotcha and gotcha_core is now documented: struct fields, trait methods, the macro-generated router methods (get/post/…), the Operable descriptor, the task scheduler. Denied rather than warned, so an undocumented public item fails the build instead of quietly accumulating — which is exactly how it reached 64.

4. The README is the crate documentation

#![doc = include_str!("../README.md")], so the crate front page and the repository landing page cannot drift apart — and the README's examples become doctests. The README had already rotted once (#28); now it can't.

Three of its five examples compile and are tested. The two that need an optional feature (#[api] needs openapi, TaskScheduler needs task) are marked ignore, because an included README cannot be feature-gated and the matrix runs combinations where those features are off.

The flagship examples were also fixed rather than merely annotated — the Advanced Trait API example referenced an undefined AppState and get_user, so nobody copying it could have compiled it. It now defines both, and demonstrates #[config] / #[state] extraction.

Two traps worth recording

include_str! pointing outside the crate directory breaks the published crate. Caught with cargo publish --dry-run:

error: couldn't read `src/../../README.md`: No such file or directory

Cargo packages the README at the package root, so the workspace path and the packaged path differ. gotcha/README.md is now a symlink to the repository README, which makes include_str!("../README.md") resolve correctly in both.

A bare ``` fence is compiled as Rust by rustdoc. The architecture diagram failed 28 parse errors until it was marked text.

Verification

• Doctests: 34 passed, 0 failed
• Every feature combination builds and tests (none / openapi / all)
• cargo clippy --all-features --workspace, cargo fmt --check
• Nightly RUSTDOCFLAGS="--cfg docsrs" cargo doc --all-features with no warnings (the LICENSE relative link was made absolute, since rustdoc can't resolve it)

🤖 Generated with Claude Code