Test guide and README using stable 'doc_comment'.

README.md

@@ -77,7 +77,7 @@ Rocket ships with an extensive number of examples in the `examples/` directory
 which can be compiled and run with Cargo. For instance, the following sequence
 of commands builds and runs the `Hello, world!` example:
 
-```
+```sh
 cd examples/hello_world
 cargo run
 ```

core/codegen/src/bang/test_guide.rs

@@ -7,21 +7,17 @@ use devise::proc_macro2::TokenStream;
 
 pub fn _macro(input: proc_macro::TokenStream) -> devise::Result<TokenStream> {
     let root_glob = syn::parse::<LitStr>(input.into())?;
-    let modules = entry_to_modules(&root_glob)
+    let tests = entry_to_tests(&root_glob)
         .map_err(|e| root_glob.span().error(format!("failed to read: {}", e)))?;
 
-    Ok(quote_spanned!(root_glob.span() =>
-        #[allow(dead_code)]
-        #[allow(non_camel_case_types)]
-        mod test_site_guide { #(#modules)* }
-    ).into())
+    Ok(quote!(#(#tests)*))
 }
 
-fn entry_to_modules(root_glob: &LitStr) -> Result<Vec<TokenStream>, Box<dyn Error>> {
+fn entry_to_tests(root_glob: &LitStr) -> Result<Vec<TokenStream>, Box<dyn Error>> {
     let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").expect("MANIFEST_DIR");
     let full_glob = Path::new(&manifest_dir).join(&root_glob.value()).display().to_string();
 
-    let mut modules = vec![];
+    let mut tests = vec![];
     for path in glob::glob(&full_glob).map_err(Box::new)? {
         let path = path.map_err(Box::new)?;
         let name = path.file_name()
@@ -32,11 +28,8 @@ fn entry_to_modules(root_glob: &LitStr) -> Result<Vec<TokenStream>, Box<dyn Erro
 
         let ident = Ident::new(&name, root_glob.span());
         let full_path = Path::new(&manifest_dir).join(&path).display().to_string();
-        modules.push(quote_spanned!(root_glob.span() =>
-            #[doc(include = #full_path)]
-            struct #ident;
-        ))
+        tests.push(quote_spanned!(root_glob.span() => doc_comment::doctest!(#full_path, #ident);))
     }
 
-    Ok(modules)
+    Ok(tests)
 }

site/guide/3-overview.md

@@ -251,13 +251,16 @@ stalls, or sometimes even deadlocks can occur.
 
   ```rust
   # #[macro_use] extern crate rocket;
+  use std::io;
   use rocket::tokio::task::spawn_blocking;
+  use rocket::response::Debug;
 
   #[get("/blocking_task")]
-  async fn blocking_task() -> Vec<u8> {
-      // In a real application, we would use rocket::response::NamedFile
-      spawn_blocking(|| {
-          std::fs::read("data.txt").expect("failed to read file")
-      }).await.unwrap()
+  async fn blocking_task() -> Result<Vec<u8>, Debug<io::Error>> {
+      // In a real app, we'd use rocket::response::NamedFile or tokio::fs::File.
+      let io_result = spawn_blocking(|| std::fs::read("data.txt")).await
+        .map_err(|join_err| io::Error::new(io::ErrorKind::Interrupted, join_err))?;
+
+      Ok(io_result?)
   }
   ```

site/tests/Cargo.toml

@@ -5,8 +5,9 @@ workspace = "../../"
 edition = "2018"
 publish = false
 
-[dependencies]
+[dev-dependencies]
 rocket = { path = "../../core/lib" }
+doc-comment = "0.3"
 rocket_contrib = { path = "../../contrib/lib", features = ["json", "tera_templates", "diesel_sqlite_pool"] }
 serde = { version = "1.0", features = ["derive"] }
 rand = "0.7"

site/tests/src/lib.rs

@@ -1,4 +1,9 @@
-#![cfg_attr(test, feature(external_doc))]
+#[cfg(any(test, doctest))]
+mod site_guide {
+    rocket::rocket_internal_guide_tests!("../guide/*.md");
+}
 
-#[cfg(test)]
-rocket::rocket_internal_guide_tests!("../guide/*.md");
+#[cfg(any(test, doctest))]
+mod readme {
+    doc_comment::doctest!("../../../README.md", readme);
+}