From 63fae9ecce888df155989c41c199801ab0346a71 Mon Sep 17 00:00:00 2001
From: Nathan Stocks <cleancut@github.com>
Date: Wed, 30 Jul 2025 17:13:08 -0600
Subject: [PATCH 1/2] Include the readme in rustdoc

---
 crates/twirp-build/src/lib.rs |  2 ++
 crates/twirp/README.md        | 18 +++++++++++++++---
 crates/twirp/src/lib.rs       |  2 ++
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/crates/twirp-build/src/lib.rs b/crates/twirp-build/src/lib.rs
index 8c3e651..90712ba 100644
--- a/crates/twirp-build/src/lib.rs
+++ b/crates/twirp-build/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../../twirp/README.md")]
+
 use quote::{format_ident, quote};
 
 /// Generates twirp services for protobuf rpc service definitions.
diff --git a/crates/twirp/README.md b/crates/twirp/README.md
index 68c60c6..ef2629f 100644
--- a/crates/twirp/README.md
+++ b/crates/twirp/README.md
@@ -34,7 +34,11 @@ prost-build = "0.13"
 
 Add a `build.rs` file to your project to compile the protos and generate Rust code:
 
-```rust
+<!--
+`rust` gets syntax highlighting in GitHub UI and Rustdoc contexts
+` ,ignore` (including the space) makes rust tests ignore the code without breaking syntax highlighting
+-->
+```rust ,ignore
 fn main() {
     let proto_source_files = ["./service.proto"];
 
@@ -55,7 +59,11 @@ This generates code that you can find in `target/build/your-project-*/out/exampl
 
 Include the generated code, create a router, register your service, and then serve those routes in the hyper server:
 
-```rust
+<!--
+`rust` gets syntax highlighting in GitHub UI and Rustdoc contexts
+` ,ignore` (including the space) makes rust tests ignore the code without breaking syntax highlighting
+-->
+```rust ,ignore
 mod haberdash {
     include!(concat!(env!("OUT_DIR"), "/service.haberdash.v1.rs"));
 }
@@ -93,7 +101,11 @@ This code creates an `axum::Router`, then hands it off to `axum::serve()` to han
 
 On the client side, you also get a generated twirp client (based on the rpc endpoints in your proto). Include the generated code, create a client, and start making rpc calls:
 
-``` rust
+<!--
+`rust` gets syntax highlighting in GitHub UI and Rustdoc contexts
+` ,ignore` (including the space) makes rust tests ignore the code without breaking syntax highlighting
+-->
+```rust ,ignore
 mod haberdash {
     include!(concat!(env!("OUT_DIR"), "/service.haberdash.v1.rs"));
 }
diff --git a/crates/twirp/src/lib.rs b/crates/twirp/src/lib.rs
index d660a7e..d5de453 100644
--- a/crates/twirp/src/lib.rs
+++ b/crates/twirp/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 pub mod client;
 pub mod error;
 pub mod headers;

From 75494af06a535be76a1be4421585cc640a6a102e Mon Sep 17 00:00:00 2001
From: Nathan Stocks <cleancut@github.com>
Date: Wed, 30 Jul 2025 17:15:23 -0600
Subject: [PATCH 2/2] fix title, point to respective readmes

---
 crates/twirp-build/src/lib.rs | 2 +-
 crates/twirp/README.md        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/twirp-build/src/lib.rs b/crates/twirp-build/src/lib.rs
index 90712ba..7481a5f 100644
--- a/crates/twirp-build/src/lib.rs
+++ b/crates/twirp-build/src/lib.rs
@@ -1,4 +1,4 @@
-#![doc = include_str!("../../twirp/README.md")]
+#![doc = include_str!("../README.md")]
 
 use quote::{format_ident, quote};
 
diff --git a/crates/twirp/README.md b/crates/twirp/README.md
index ef2629f..b08aa67 100644
--- a/crates/twirp/README.md
+++ b/crates/twirp/README.md
@@ -1,4 +1,4 @@
-# `twirp-build`
+# `twirp`
 
 [Twirp is an RPC protocol](https://twitchtv.github.io/twirp/docs/spec_v7.html) based on HTTP and Protocol Buffers (proto). The protocol uses HTTP URLs to specify the RPC endpoints, and sends/receives proto messages as HTTP request/response bodies. Services are defined in a [.proto file](https://developers.google.com/protocol-buffers/docs/proto3), allowing easy implementation of RPC services with auto-generated clients and servers in different languages.