docs(tonic-build): remove doc-difference between lib.rs and Readme (#2308)

* doc: try to improve the doc-disparity between `tonic-build`'s `lib.rs` and the readme

* Fix indentation

* fix the doctests

* fix a typo and retes an assumption

* Change `compile_fail` to `ignore`

Co-authored-by: tottoto <[email protected]>

---------

Co-authored-by: tottoto <[email protected]>

Author: CommanderStorm

tonic-build/README.md

@@ -2,6 +2,15 @@
 
 Compiles proto files via prost and generates service stubs and proto definitions for use with tonic.
 
+# Feature flags
+
+- `cleanup-markdown`: Enables cleaning up documentation from the generated code.
+  Useful when documentation of the generated code fails `cargo test --doc` for example.
+  The `prost` feature must be enabled to use this feature.
+- `prost`: Enables usage of prost generator (enabled by default).
+- `transport`: Enables generation of `connect` method using `tonic::transport::Channel`
+  (enabled by default).
+
 ## Features
 
 Required dependencies
@@ -15,21 +24,22 @@ prost = "<prost-version>"
 tonic-build = "<tonic-version>"
 ```
 
-## Examples
+## Getting Started
 
-### Simple
+`tonic-build` works by being included as a [`build.rs` file](https://doc.rust-lang.org/cargo/reference/build-scripts.html) at the root of the binary/library.
 
-In `build.rs`:
-```rust
+You can rely on the defaults via
+
+```rust,no_run
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     tonic_build::compile_protos("proto/service.proto")?;
     Ok(())
 }
 ```
 
-### Configuration
+Or configure the generated code deeper via
 
-```rust
+```rust,no_run
 fn main() -> Result<(), Box<dyn std::error::Error>> {
    tonic_build::configure()
         .build_server(false)
@@ -40,20 +50,37 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
    Ok(())
 }
 ```
-See [more examples here](https://github.com/hyperium/tonic/tree/master/examples)
+
+For further details how to use the generated client/server, see the [examples here](https://github.com/hyperium/tonic/tree/master/examples) or the Google APIs example below.
+
+
+## NixOS related hints
+
+On NixOS, it is better to specify the location of `PROTOC` and `PROTOC_INCLUDE` explicitly.
+
+```bash
+$ export PROTOBUF_LOCATION=$(nix-env -q protobuf --out-path --no-name)
+$ export PROTOC=$PROTOBUF_LOCATION/bin/protoc
+$ export PROTOC_INCLUDE=$PROTOBUF_LOCATION/include
+$ cargo build
+```
+
+The reason being that if `prost_build::compile_protos` fails to generate the resultant package,
+the failure is not obvious until the `include!(concat!(env!("OUT_DIR"), "/resultant.rs"));`
+fails with `No such file or directory` error.
 
 ### Google APIs example
 A good way to use Google API is probably using git submodules.
 
 So suppose in our `proto` folder we do:
-```
+```bash
 git submodule add https://github.com/googleapis/googleapis
 
 git submodule update --remote
 ```
 
 And a bunch of Google proto files in structure will be like this:
-```
+```raw
 ├── googleapis
 │   └── google
 │       ├── api
@@ -68,21 +95,23 @@ And a bunch of Google proto files in structure will be like this:
 │               └── schema.proto
 ```
 
-Then we can generate Rust code via this setup in our `build.rs`
-```rust
-fn main() {
+Then we can generate Rust code via this setup in our `build.rs`:
+
+```rust,no_run
+fn main() -> Result<(), Box<dyn std::error::Error>> {
     tonic_build::configure()
         .build_server(false)
         //.out_dir("src/google")  // you can change the generated code's location
         .compile_protos(
             &["proto/googleapis/google/pubsub/v1/pubsub.proto"],
             &["proto/googleapis"], // specify the root location to search proto dependencies
-        ).unwrap();
+        )?;
+    Ok(())
 }
 ```
 
 Then you can reference the generated Rust like this this in your code:
-```rust
+```rust,ignore
 pub mod api {
     tonic::include_proto!("google.pubsub.v1");
 }
@@ -92,7 +121,7 @@ use api::{publisher_client::PublisherClient, ListTopicsRequest};
 Or if you want to save the generated code in your own code base,
 you can uncomment the line `.out_dir(...)` above, and in your lib file
 config a mod like this:
-```rust
+```rust,ignore
 pub mod google {
     #[path = ""]
     pub mod pubsub {

tonic-build/src/lib.rs

@@ -1,65 +1,4 @@
-//! `tonic-build` compiles `proto` files via `prost` and generates service stubs
-//! and proto definitions for use with `tonic`.
-//!
-//! # Feature flags
-//!
-//! - `cleanup-markdown`: Enables cleaning up documentation from the generated code. Useful
-//!   when documentation of the generated code fails `cargo test --doc` for example. The
-//!   `prost` feature must be enabled to use this feature.
-//! - `prost`: Enables usage of prost generator (enabled by default).
-//! - `transport`: Enables generation of `connect` method using `tonic::transport::Channel`
-//!   (enabled by default).
-//!
-//! # Required dependencies
-//!
-//! ```toml
-//! [dependencies]
-//! tonic = <tonic-version>
-//! prost = <prost-version>
-//!
-//! [build-dependencies]
-//! tonic-build = <tonic-version>
-//! ```
-//!
-//! # Examples
-//! Simple
-//!
-//! ```rust,no_run
-//! fn main() -> Result<(), Box<dyn std::error::Error>> {
-//!     tonic_build::compile_protos("proto/service.proto")?;
-//!     Ok(())
-//! }
-//! ```
-//!
-//! Configuration
-//!
-//! ```rust,no_run
-//! fn main() -> Result<(), Box<dyn std::error::Error>> {
-//!    tonic_build::configure()
-//!         .build_server(false)
-//!         .compile_protos(
-//!             &["proto/helloworld/helloworld.proto"],
-//!             &["proto/helloworld"],
-//!         )?;
-//!    Ok(())
-//! }
-//!```
-//!
-//! ## NixOS related hints
-//!
-//! On NixOS, it is better to specify the location of `PROTOC` and `PROTOC_INCLUDE` explicitly.
-//!
-//! ```bash
-//! $ export PROTOBUF_LOCATION=$(nix-env -q protobuf --out-path --no-name)
-//! $ export PROTOC=$PROTOBUF_LOCATION/bin/protoc
-//! $ export PROTOC_INCLUDE=$PROTOBUF_LOCATION/include
-//! $ cargo build
-//! ```
-//!
-//! The reason being that if `prost_build::compile_protos` fails to generate the resultant package,
-//! the failure is not obvious until the `include!(concat!(env!("OUT_DIR"), "/resultant.rs"));`
-//! fails with `No such file or directory` error.
-
+#![doc = include_str!("../README.md")]
 #![recursion_limit = "256"]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/website/master/public/img/icons/tonic.svg"