Repository: tower-rs/tower
Pull request #527 (2021-01-12 19:03:02)

chore: improve README docs, add links
This branch updates the READMEs for all Tower crates.

I've added the lib.rs docs to the `tower` crate's README, and added
crates.io, docs.rs, and updated CI badges to all the crates READMEs.
Since we no longer use Azure Pipelines for CI or Gitter for chat, I've
removed those badges and replaced them with GitHub Actions and Discord
badges, respectively.

I also fixed a typo in the `tower` lib.rs docs that was breaking some of the
RustDoc links, since I noticed it after copying those docs into the README.

Signed-off-by: Eliza Weisman <eliza@buoyant.io>


Patch:
diff --git a/README.md b/README.md
index f9f2fcb..33acecf 100644
--- a/README.md
+++ b/README.md
@@ -3,13 +3,25 @@
 Tower is a library of modular and reusable components for building robust
 networking clients and servers.
 
-[![Build Status][azure-badge]][azure-url]
-[![Gitter][gitter-badge]][gitter-url]
-
-[azure-badge]: https://dev.azure.com/tower-rs/Tower/_apis/build/status/tower-rs.tower?branchName=master
-[azure-url]: https://dev.azure.com/tower-rs/Tower/_build/latest?definitionId=1&branchName=master
-[gitter-badge]: https://badges.gitter.im/tower-rs/tower.svg
-[gitter-url]: https://gitter.im/tower-rs/tower
+[![Crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![Documentation (master)][docs-master-badge]][docs-master-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+[![Discord chat][discord-badge]][discord-url]
+
+[crates-badge]: https://img.shields.io/crates/v/tower.svg
+[crates-url]: https://crates.io/crates/tower
+[docs-badge]: https://docs.rs/tower/badge.svg
+[docs-url]: https://docs.rs/tower
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
+[docs-master-url]: https://tower-rs.github.io/tower/tower
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: LICENSE
+[actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg
+[actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI
+[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
+[discord-url]: https://discord.gg/EeF3cQw
 
 ## Overview
 
diff --git a/tower-layer/README.md b/tower-layer/README.md
index b7def25..48f9dbb 100644
--- a/tower-layer/README.md
+++ b/tower-layer/README.md
@@ -1,6 +1,26 @@
 # Tower Layer
 
-Decorates a `Service`, transforming either the request or the response.
+Decorates a [Tower] `Service`, transforming either the request or the response.
+
+[![Crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![Documentation (master)][docs-master-badge]][docs-master-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+[![Discord chat][discord-badge]][discord-url]
+
+[crates-badge]: https://img.shields.io/crates/v/tower-layer.svg
+[crates-url]: https://crates.io/crates/tower-layer
+[docs-badge]: https://docs.rs/tower-layer/badge.svg
+[docs-url]: https://docs.rs/tower-layer
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
+[docs-master-url]: https://tower-rs.github.io/tower/tower_layer
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: LICENSE
+[actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg
+[actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI
+[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
+[discord-url]: https://discord.gg/EeF3cQw
 
 ## Overview
 
@@ -19,3 +39,5 @@ This project is licensed under the [MIT license](LICENSE).
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in Tower by you, shall be licensed as MIT, without any additional
 terms or conditions.
+
+[Tower]: https://crates.io/crates/tower
\ No newline at end of file
diff --git a/tower-service/README.md b/tower-service/README.md
index 240649e..3f2766d 100644
--- a/tower-service/README.md
+++ b/tower-service/README.md
@@ -1,10 +1,30 @@
 # Tower Service
 
-The foundational `Service` trait that Tower is based on.
+The foundational `Service` trait that [Tower] is based on.
+
+[![Crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![Documentation (master)][docs-master-badge]][docs-master-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+[![Discord chat][discord-badge]][discord-url]
+
+[crates-badge]: https://img.shields.io/crates/v/tower-service.svg
+[crates-url]: https://crates.io/crates/tower-service
+[docs-badge]: https://docs.rs/tower-service/badge.svg
+[docs-url]: https://docs.rs/tower-service
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
+[docs-master-url]: https://tower-rs.github.io/tower/tower_service
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: LICENSE
+[actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg
+[actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI
+[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
+[discord-url]: https://discord.gg/EeF3cQw
 
 ## Overview
 
-The [`Service`] trait provides the foundation upon which Tower is built. It is a
+The [`Service`] trait provides the foundation upon which [Tower] is built. It is a
 simple, but powerful trait. At its heart, `Service` is just an asynchronous
 function of request to response.
 
@@ -24,7 +44,7 @@ By using standardizing the interface, middleware can be created. Middleware
 middleware may take actions such as modify the request.
 
 [`Service`]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
-
+[Tower]: https://crates.io/crates/tower
 ## License
 
 This project is licensed under the [MIT license](LICENSE).
diff --git a/tower/README.md b/tower/README.md
index fe56051..7690118 100644
--- a/tower/README.md
+++ b/tower/README.md
@@ -3,12 +3,103 @@
 Tower is a library of modular and reusable components for building robust
 networking clients and servers.
 
+[![Crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![Documentation (master)][docs-master-badge]][docs-master-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+[![Discord chat][discord-badge]][discord-url]
+
+[crates-badge]: https://img.shields.io/crates/v/tower.svg
+[crates-url]: https://crates.io/crates/tower
+[docs-badge]: https://docs.rs/tower/badge.svg
+[docs-url]: https://docs.rs/tower
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
+[docs-master-url]: https://tower-rs.github.io/tower/tower
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: LICENSE
+[actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg
+[actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI
+[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
+[discord-url]: https://discord.gg/EeF3cQw
 ## Overview
 
 Tower aims to make it as easy as possible to build robust networking clients and
 servers. It is protocol agnostic, but is designed around a request / response
 pattern. If your protocol is entirely stream based, Tower may not be a good fit.
 
+Tower provides a simple core abstraction, the [`Service`] trait, which
+represents an asynchronous function taking a request and returning either a
+response or an error. This abstraction can be used to model both clients and
+servers.
+
+Generic components, like [timeouts], [rate limiting], and [load balancing],
+can be modeled as [`Service`]s that wrap some inner service and apply
+additional behavior before or after the inner service is called. This allows
+implementing these components in a protocol-agnostic, composable way. Typically,
+such services are referred to as _middleware_.
+
+An additional abstraction, the [`Layer`] trait, is used to compose
+middleware with [`Service`]s. If a [`Service`] can be thought of as an
+asynchronous function from a request type to a response type, a [`Layer`] is
+a function taking a [`Service`] of one type and returning a [`Service`] of a
+different type. The [`ServiceBuilder`] type is used to add middleware to a
+service by composing it with multiple multiple [`Layer`]s.
+
+### The Tower Ecosystem
+
+Tower is made up of the following crates:
+
+* [`tower`] (this crate)
+* [`tower-service`]
+* [`tower-layer`]
+* [`tower-test`]
+
+Since the [`Service`] and [`Layer`] traits are important integration points
+for all libraries using Tower, they are kept as stable as possible, and
+breaking changes are made rarely. Therefore, they are defined in separate
+crates, [`tower-service`] and [`tower-layer`]. This crate contains
+re-exports of those core traits, implementations of commonly-used
+middleware, and [utilities] for working with [`Service`]s and [`Layer`]s.
+Finally, the [`tower-test`] crate provides tools for testing programs using
+Tower.
+
+## Usage
+
+The various middleware implementations provided by this crate are feature
+flagged, so that users can only compile the parts of Tower they need. By
+default, all the optional middleware are disabled.
+
+To get started using all of Tower's optional middleware, add this to your
+`Cargo.toml`:
+
+```toml
+tower = { version = "0.4", features = ["full"] }
+```
+
+Alternatively, you can only enable some features. For example, to enable
+only the [`retry`] and [`timeout`][timeouts] middleware, write:
+
+```toml
+tower = { version = "0.4", features = ["retry", "timeout"] }
+```
+
+See [here](modules) for a complete list of all middleware provided by
+Tower.
+
+[`Service`]: https://docs.rs/tower/latest/tower/trait.Service.html
+[`Layer`]: https://docs.rs/tower/latest/tower/trait.Layer.html
+[timeouts]: https://docs.rs/tower/latest/tower/timeout/
+[rate limiting]: https://docs.rs/tower/latest/tower/limit/rate
+[load balancing]: https://docs.rs/tower/latest/tower/balance/
+[`ServiceBuilder`]: https://docs.rs/tower/latest/tower/struct.ServiceBuilder.html
+[utilities]: https://docs.rs/tower/latest/tower/trait.ServiceExt.html
+[`tower`]: https://crates.io/crates/tower
+[`tower-service`]: https://crates.io/crates/tower-service
+[`tower-layer`]: https://crates.io/crates/tower-layer
+[`tower-test`]: https://crates.io/crates/tower-test
+[`retry`]: https://docs.rs/tower/latest/tower/retry
+
 ## License
 
 This project is licensed under the [MIT license](LICENSE).
diff --git a/tower/src/lib.rs b/tower/src/lib.rs
index fe4887f..b7e2eba 100644
--- a/tower/src/lib.rs
+++ b/tower/src/lib.rs
@@ -67,7 +67,7 @@
 //! ```
 //!
 //! Alternatively, you can only enable some features. For example, to enable
-//! only the [`retry`] and [`timeout`] middleware, write:
+//! only the [`retry`] and [`timeout`][timeouts] middleware, write:
 //!
 //! ```toml
 //! tower = { version = "0.4", features = ["retry", "timeout"] }
@@ -77,7 +77,7 @@
 //! Tower.
 //!
 //! [`Service`]: crate::Service
-//! [`Layer]: crate::Layer
+//! [`Layer`]: crate::Layer
 //! [timeouts]: crate::timeout
 //! [rate limiting]: crate::limit::rate
 //! [load balancing]: crate::balance
@@ -88,7 +88,6 @@
 //! [`tower-layer`]: https://crates.io/crates/tower-layer
 //! [`tower-test`]: https://crates.io/crates/tower-test
 //! [`retry`]: crate::retry
-//! [`timeout`]: crate::timeout
 #[macro_use]
 pub(crate) mod macros;
 #[cfg(feature = "balance")]


Test patch:
diff --git a/tower-test/README.md b/tower-test/README.md
index df0a197..be9b1e7 100644
--- a/tower-test/README.md
+++ b/tower-test/README.md
@@ -2,6 +2,26 @@
 
 Utilities for writing client and server `Service` tests.
 
+[![Crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![Documentation (master)][docs-master-badge]][docs-master-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+[![Discord chat][discord-badge]][discord-url]
+
+[crates-badge]: https://img.shields.io/crates/v/tower-test.svg
+[crates-url]: https://crates.io/crates/tower-test
+[docs-badge]: https://docs.rs/tower-test/badge.svg
+[docs-url]: https://docs.rs/tower-test
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
+[docs-master-url]: https://tower-rs.github.io/tower/tower_test
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: LICENSE
+[actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg
+[actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI
+[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
+[discord-url]: https://discord.gg/EeF3cQw
+
 ## License
 
 This project is licensed under the [MIT license](LICENSE).