-
Notifications
You must be signed in to change notification settings - Fork 15
Add user guide and adoption-helpful README signposts #47
Copy link
Copy link
Open
Description
The README is detailed about API surface and performance, but new adopters miss several signals:
- No long-form documentation beyond the README and rustdoc, so deeper questions ("how do tower layers compose with the connect router?", "how do I read identity from a custom auth layer in my handler?") require reading source.
- No MSRV declared anywhere outside the Cargo manifest.
- No stability statement (pre-1.0, API surface settling).
- No top-of-README pointer to the
examples/directory.
Plan
Add docs/guide.md as the long-form companion, covering:
- Installation (deps, MSRV, feature flags)
- Quick start
- Code generation (both build paths)
- Implementing servers (handler signatures, Context, errors, headers/trailers, registering)
- Streaming RPCs (all 4 types)
- Tower middleware (layer composition, identity passthrough via Context::extensions)
- Hosting (axum, standalone, TLS)
- Clients (HttpClient, ClientConfig, CallOptions, response access patterns, custom transports)
- Errors and status codes
- Compression
- Examples directory tour
The guide references the streaming-tour and middleware examples (added in #45 / PR #46) for runnable patterns rather than duplicating those examples inline.
README updates: add a Status / MSRV / Documentation block near the top with pointers to the guide, examples, and docs.rs. Add a focused "Streaming, middleware, TLS" subsection at the end of Quick Start linking into specific guide sections + examples.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Type
Fields
Give feedbackNo fields configured for issues without a type.