Skip to content

Add user guide and adoption-helpful README signposts #47

@iainmcgin

Description

@iainmcgin

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:

  1. Installation (deps, MSRV, feature flags)
  2. Quick start
  3. Code generation (both build paths)
  4. Implementing servers (handler signatures, Context, errors, headers/trailers, registering)
  5. Streaming RPCs (all 4 types)
  6. Tower middleware (layer composition, identity passthrough via Context::extensions)
  7. Hosting (axum, standalone, TLS)
  8. Clients (HttpClient, ClientConfig, CallOptions, response access patterns, custom transports)
  9. Errors and status codes
  10. Compression
  11. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions