Manage source snippets as snapshots (#115)

We extend the system we built in #114 for error outputs to source code
snippets.

.github/workflows/docs.yml

@@ -53,7 +53,7 @@ jobs:
           name: tutorial_generator
           path: doc_examples/tutorial_generator/target/debug/tutorial_generator
 
-  build_docs:
+  is_up_to_date:
     runs-on: ubuntu-latest
     needs:
       - build_pavex_cli
@@ -72,24 +72,6 @@ jobs:
           components: rust-docs-json
       - name: Install Rust stable toolchain
         uses: actions-rust-lang/[email protected]
-      - name: Cache dependencies
-        uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: "./libs -> ./libs/target"
-          key: "build-pavex-docs"
-      - name: Build API reference
-        run: |
-          cd libs
-          cargo doc --package pavex --no-deps
-      - name: Copy API reference files
-        run: |
-          mkdir -p docs/api_reference
-          cp -r libs/target/doc/* docs/api_reference
-      - name: Link Checker
-        uses: lycheeverse/lychee-action@v1
-        with:
-          fail: true
-          args: --base . --exclude-loopback --exclude-path="docs/api_reference" --require-https --verbose --no-progress docs
       - name: Download pavex CLI artifact
         uses: actions/download-artifact@v3
         with:
@@ -111,6 +93,32 @@ jobs:
         run: |
           cd doc_examples/quickstart
           tutorial_generator --verify
+
+  build_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust stable toolchain
+        uses: actions-rust-lang/[email protected]
+      - name: Cache dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "./libs -> ./libs/target"
+          key: "build-pavex-docs"
+      - name: Build API reference
+        run: |
+          cd libs
+          cargo doc --package pavex --no-deps
+      - name: Copy API reference files
+        run: |
+          mkdir -p docs/api_reference
+          cp -r libs/target/doc/* docs/api_reference
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v1
+        with:
+          fail: true
+          args: --base . --exclude-loopback --exclude-path="docs/api_reference" --require-https --verbose --no-progress docs
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
       - name: Set up Docker Buildx

doc_examples/quickstart/02-new_submodule.snap

@@ -0,0 +1,4 @@
+```rust title="demo/src/routes/mod.rs" hl_lines="1"
+pub mod greet;
+pub mod status;
+```

doc_examples/quickstart/02-register_new_route.snap

@@ -0,0 +1,16 @@
+```rust title="demo/src/blueprint.rs" hl_lines="9 10 11 12 13"
+\\ [...]
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    register_common_constructors(&mut bp);
+
+    add_telemetry_middleware(&mut bp);
+
+    bp.route(GET, "/api/ping", f!(crate::routes::status::ping));
+    bp.route(
+        GET,
+        "/api/greet/:name", /* (1)! */
+        f!(crate::routes::greet::greet),
+    );
+    bp
+```

doc_examples/quickstart/02-route_def.snap

@@ -0,0 +1,7 @@
+```rust title="demo/src/routes/greet.rs"
+use pavex::response::Response;
+
+pub fn greet() -> Response {
+    todo!()
+}
+```

doc_examples/quickstart/02.patch

@@ -1,9 +1,10 @@
 diff --git a/demo/src/blueprint.rs b/demo/src/blueprint.rs
+index 4a196d8..0a6857d 100644
 --- a/demo/src/blueprint.rs
 +++ b/demo/src/blueprint.rs
-@@ -12,6 +12,11 @@ pub fn blueprint() -> Blueprint {
+@@ -11,6 +11,11 @@ pub fn blueprint() -> Blueprint {
      add_telemetry_middleware(&mut bp);
-
+ 
      bp.route(GET, "/api/ping", f!(crate::routes::status::ping));
 +    bp.route(
 +        GET,
@@ -12,9 +13,10 @@ diff --git a/demo/src/blueprint.rs b/demo/src/blueprint.rs
 +    );
      bp
  }
- // <--8-- [start:blueprint_definition]
+
 diff --git a/demo/src/routes/greet.rs b/demo/src/routes/greet.rs
 new file mode 100644
+index 0000000..38ec1e3
 --- /dev/null
 +++ b/demo/src/routes/greet.rs
 @@ -0,0 +1,5 @@
@@ -24,10 +26,9 @@ new file mode 100644
 +    todo!()
 +}
 diff --git a/demo/src/routes/mod.rs b/demo/src/routes/mod.rs
+index 822c729..d709a21 100644
 --- a/demo/src/routes/mod.rs
 +++ b/demo/src/routes/mod.rs
 @@ -1 +1,2 @@
--pub mod status;
-\ No newline at end of file
 +pub mod greet;
-+pub mod status;
+ pub mod status;

doc_examples/quickstart/03-route_def.snap

@@ -0,0 +1,13 @@
+```rust title="demo/src/routes/greet.rs"
+use pavex::request::RouteParams;
+use pavex::response::Response;
+
+#[RouteParams]
+pub struct GreetParams {
+    pub name: String, /* (1)! */
+}
+
+pub fn greet(params: RouteParams<GreetParams> /* (2)! */) -> Response {
+    todo!()
+}
+```

doc_examples/quickstart/03.patch

@@ -9,7 +9,7 @@ index 38ec1e3..adfbbd5 100644
 -pub fn greet() -> Response {
 +#[RouteParams]
 +pub struct GreetParams {
-+    pub name: String,
++    pub name: String /* (1)! */
 +}
 +
 +pub fn greet(params: RouteParams<GreetParams> /* (2)! */) -> Response {

doc_examples/quickstart/04-register_common_invocation.snap

@@ -0,0 +1,9 @@
+```rust title="demo/src/blueprint.rs" hl_lines="4"
+\\ [...]
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    register_common_constructors(&mut bp);
+    \\ [...]
+    bp
+}
+```

doc_examples/quickstart/04-route_def.snap

@@ -0,0 +1,16 @@
+```rust title="demo/src/routes/greet.rs"
+use pavex::request::route::RouteParams;
+use pavex::response::Response;
+
+#[RouteParams]
+pub struct GreetParams {
+    pub name: String,
+}
+
+pub fn greet(params: RouteParams<GreetParams>) -> Response {
+    let GreetParams { name }/* (1)! */ = params.0;
+    Response::ok() // (2)!
+        .set_typed_body(format!("Hello, {name}!")) // (3)!
+        .box_body()
+}
+```

doc_examples/quickstart/04-route_params_constructor.snap

@@ -0,0 +1,11 @@
+```rust title="demo/src/blueprint.rs" hl_lines="4 5 6 7"
+\\ [...]
+fn register_common_constructors(bp: &mut Blueprint) {
+    \\ [...]
+    bp.constructor(
+        f!(pavex::request::route::RouteParams::extract),
+        Lifecycle::RequestScoped,
+    )
+    \\ [...]
+}
+```

doc_examples/quickstart/04.patch

@@ -1,15 +1,16 @@
 diff --git a/demo/src/routes/greet.rs b/demo/src/routes/greet.rs
-index adfbbd5..fbcb3fc 100644
+index 0d94360..fbcb3fc 100644
 --- a/demo/src/routes/greet.rs
 +++ b/demo/src/routes/greet.rs
-@@ -1,4 +1,4 @@
+@@ -1,11 +1,14 @@
 -use pavex::request::RouteParams;
 +use pavex::request::route::RouteParams;
  use pavex::response::Response;
 
  #[RouteParams]
-@@ -6,6 +6,9 @@ pub struct GreetParams {
-     pub name: String,
+ pub struct GreetParams {
+-    pub name: String, /* (1)! */
++    pub name: String,
  }
 
 -pub fn greet(params: RouteParams<GreetParams> /* (2)! */) -> Response {

doc_examples/quickstart/05-bis.patch

@@ -1,8 +1,7 @@
 diff --git a/demo/src/blueprint.rs b/demo/src/blueprint.rs
-index f1434bb..88fd441 100644
 --- a/demo/src/blueprint.rs
 +++ b/demo/src/blueprint.rs
-@@ -12,11 +12,7 @@ pub fn blueprint() -> Blueprint {
+@@ -11,11 +11,7 @@ pub fn blueprint() -> Blueprint {
      add_telemetry_middleware(&mut bp);
 
      bp.route(GET, "/api/ping", f!(crate::routes::status::ping));
@@ -14,24 +13,16 @@ index f1434bb..88fd441 100644
 +    bp.route(GET, "/api/greet/:name", f!(crate::routes::greet::greet));
      bp
  }
- // --8<-- [end:blueprint_definition]
+
 diff --git a/demo/src/routes/greet.rs b/demo/src/routes/greet.rs
-index 220a89e..526c16f 100644
 --- a/demo/src/routes/greet.rs
 +++ b/demo/src/routes/greet.rs
-@@ -11,14 +11,12 @@ pub struct GreetParams {
+@@ -8,7 +8,7 @@ pub struct GreetParams {
      pub name: String,
  }
 
--// --8<-- [start:user_agent]
 -pub fn greet(params: RouteParams<GreetParams>, user_agent: UserAgent /* (1)! */) -> Response {
 +pub fn greet(params: RouteParams<GreetParams>, user_agent: UserAgent) -> Response {
      if let UserAgent::Unknown = user_agent {
          return Response::unauthorized()
              .set_typed_body("You must provide a `User-Agent` header")
-             .box_body();
-     }
--    // --8<-- [end:user_agent]
-     let GreetParams { name } = params.0;
-     Response::ok()
-         .set_typed_body(format!("Hello, {name}!"))

doc_examples/quickstart/05-error.snap

@@ -3,19 +3,19 @@ ERROR:
   │ instance of `demo::user_agent::UserAgent` as input, but I can't find a constructor for that
   │ type.
   │
-  │     ╭─[demo/src/blueprint.rs:14:1]
-  │  14 │     bp.route(GET, "/api/ping", f!(crate::routes::status::ping));
-  │  15 │     bp.route(GET, "/api/greet/:name", f!(crate::routes::greet::greet));
+  │     ╭─[demo/src/blueprint.rs:13:1]
+  │  13 │     bp.route(GET, "/api/ping", f!(crate::routes::status::ping));
+  │  14 │     bp.route(GET, "/api/greet/:name", f!(crate::routes::greet::greet));
   │     ·                                       ───────────────┬───────────────
   │     ·                                                      ╰── The request handler was registered here
-  │  16 │     bp
+  │  15 │     bp
   │     ╰────
-  │     ╭─[demo/src/routes/greet.rs:13:1]
-  │  13 │ 
-  │  14 │ pub fn greet(params: RouteParams<GreetParams>, user_agent: UserAgent) -> Response {
+  │     ╭─[demo/src/routes/greet.rs:10:1]
+  │  10 │ 
+  │  11 │ pub fn greet(params: RouteParams<GreetParams>, user_agent: UserAgent) -> Response {
   │     ·                                                            ────┬────
   │     ·                                                                ╰── I don't know how to construct an instance of this input parameter
-  │  15 │     if let UserAgent::Unknown = user_agent {
+  │  12 │     if let UserAgent::Unknown = user_agent {
   │     ╰────
   │   help: Register a constructor for `demo::user_agent::UserAgent`
 

doc_examples/quickstart/05-inject.snap

@@ -0,0 +1,13 @@
+```rust title="demo/src/routes/greet.rs" hl_lines="4"
+\\ [...]
+use crate::user_agent::UserAgent;
+\\ [...]
+pub fn greet(params: RouteParams<GreetParams>, user_agent: UserAgent /* (1)! */) -> Response {
+    if let UserAgent::Unknown = user_agent {
+        return Response::unauthorized()
+            .set_typed_body("You must provide a `User-Agent` header")
+            .box_body();
+    }
+    \\ [...]
+}
+```

doc_examples/quickstart/05-new_submodule.snap

@@ -0,0 +1,9 @@
+```rust title="demo/src/lib.rs" hl_lines="7"
+pub use blueprint::blueprint;
+
+mod blueprint;
+pub mod configuration;
+pub mod routes;
+pub mod telemetry;
+pub mod user_agent;
+```

doc_examples/quickstart/05-user_agent.snap

@@ -0,0 +1,8 @@
+```rust title="demo/src/user_agent.rs"
+pub enum UserAgent {
+    /// No `User-Agent` header was provided.
+    Unknown,
+    /// The value of the `User-Agent` header for the incoming request.
+    Known(String),
+}
+```