docs: improve documentation and add automated testing

.github/workflows/docs.yml

@@ -36,6 +36,13 @@ jobs:
         env:
           NIX_ACCEPT_FLAKE_CONFIG: 1
 
+      - name: Check example documentation coverage
+        run: |
+          nix develop '.#pureRust-ci' -c nu scripts/check-example-coverage.nu
+        env:
+          NIX_ACCEPT_FLAKE_CONFIG: 1
+        continue-on-error: true  # Don't fail the build, just warn
+
   publish_doc:
     name: Publish to GitHub Pages
     if: github.ref == 'refs/heads/main'

book/src/chapters/actions.md

@@ -77,52 +77,84 @@ sequenceDiagram
 Actions excel when operations take more than a few seconds and users need visibility into progress. For sub-second operations, prefer services for simplicity.
 ```
 
-## Example Patterns
+## Action Server Example
 
-**Action Server:**
+This example demonstrates an action server that computes Fibonacci sequences. The server accepts goals, publishes periodic feedback with partial results, and supports cancellation.
 
 ```rust,ignore
-let action_server = node
-    .create_action_server::<Fibonacci>("/fibonacci")
-    .build()?;
-
-loop {
-    let goal = action_server.accept_goal()?;
-
-    // Send periodic feedback
-    for i in 0..goal.order {
-        action_server.send_feedback(FeedbackMsg {
-            current: i,
-            sequence: compute_partial(i)
-        })?;
-    }
-
-    // Send final result
-    action_server.send_result(ResultMsg {
-        sequence: compute_final(goal.order)
-    })?;
-}
+{{#include ../../../crates/ros-z/examples/demo_nodes/fibonacci_action_server.rs:full_example}}
 ```
 
-**Action Client:**
+**Key points:**
+
+- **Handler Pattern**: Uses `.with_handler()` to define asynchronous goal execution
+- **Feedback Publishing**: Sends partial results periodically via `publish_feedback()`
+- **Cancellation Support**: Checks `is_cancel_requested()` and handles graceful cancellation
+- **Completion**: Uses `.succeed()` or `.canceled()` to send final result
+
+**Running the server:**
+
+```bash
+# Start Zenoh router first
+cargo run --example zenoh_router
+
+# Run the server (runs until Ctrl+C)
+cargo run --example demo_nodes_fibonacci_action_server
+```
+
+## Action Client Example
+
+This example demonstrates an action client that sends goals and monitors execution progress with feedback updates.
 
 ```rust,ignore
-let action_client = node
-    .create_action_client::<Fibonacci>("/fibonacci")
-    .build()?;
+{{#include ../../../crates/ros-z/examples/demo_nodes/fibonacci_action_client.rs:full_example}}
+```
+
+**Key points:**
 
-let goal_handle = action_client.send_goal(GoalMsg {
-    order: 10
-}).await?;
+- **Goal Sending**: Uses `send_goal()` to submit goals and get a handle
+- **Feedback Monitoring**: Spawns async task to receive and display feedback
+- **Result Handling**: Waits for completion with timeout and error handling
+- **Type Safety**: Strongly-typed goal, feedback, and result messages
 
-while let Some(feedback) = goal_handle.feedback().await {
-    println!("Progress: {}", feedback.current);
-}
+**Running the client:**
 
-let result = goal_handle.get_result().await?;
-println!("Final: {:?}", result.sequence);
+```bash
+# Basic usage - compute Fibonacci(10)
+cargo run --example demo_nodes_fibonacci_action_client
+
+# Compute Fibonacci(15)
+cargo run --example demo_nodes_fibonacci_action_client -- --order 15
+
+# Connect to specific router
+cargo run --example demo_nodes_fibonacci_action_client -- --endpoint tcp/localhost:7447
 ```
 
+## Complete Action Workflow
+
+**Terminal 1 - Start Zenoh Router:**
+
+```bash
+cargo run --example zenoh_router
+```
+
+**Terminal 2 - Start Action Server:**
+
+```bash
+cargo run --example demo_nodes_fibonacci_action_server
+```
+
+**Terminal 3 - Send Goals from Client:**
+
+```bash
+cargo run --example demo_nodes_fibonacci_action_client -- --order 10
+```
+
+You'll see:
+
+- **Client**: Goal sent, feedback updates with partial sequences, final result
+- **Server**: Goal received, executing with feedback, completion status
+
 ```admonish warning
 Always implement timeout mechanisms for action clients. Long-running actions can fail or hang, and clients need graceful degradation strategies.
 ```

book/src/chapters/examples.md

@@ -1,18 +1,58 @@
 # Running Examples
 
-Once you've added ros-z to your project, you can run the included examples to see it in action.
+```admonish note
+The examples described here are part of the ros-z repository. To run them, you must first clone the repository.
+```
+
+```bash
+git clone https://github.com/ZettaScaleLabs/ros-z.git
+cd ros-z
+```
+
+## Start the Zenoh Router
+
+All examples require a Zenoh router to be running first (see [Networking](./networking.md) for why ros-z uses router-based architecture by default).
+
+## From the ros-z Repository
+
+If you're working in the ros-z repository, use the included router example:
 
-````admonish important
-**All examples require a Zenoh router to be running first** (see [Networking](./networking.md) for why ros-z uses router-based architecture by default):
 ```bash
 cargo run --example zenoh_router
 ```
-````
 
-Leave this running in a separate terminal, then run any example in another terminal.
+## From Your Own Project
+
+If you're working on your own project, you need to install a Zenoh router. Quick options:
+
+```bash
+# Using cargo
+cargo install zenohd
+
+# Using Docker
+docker run --init --net host eclipse/zenoh:latest
+
+# Using apt (Ubuntu/Debian)
+echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" | sudo tee /etc/apt/sources.list.d/zenoh.list
+sudo apt update && sudo apt install zenoh
+```
+
+Then run:
+
+```bash
+zenohd
+```
+
+```admonish tip
+See the comprehensive [Zenoh Router Installation Guide](./networking.md#running-the-zenoh-router) for all installation methods including pre-built binaries, package managers, and more.
+```
+
+---
 
 ## Available Examples
 
+Leave the router running in a separate terminal, then run any example in another terminal from the ros-z repository root:
+
 ```bash
 # Pure Rust example with custom messages (no ros-z-msgs needed)
 cargo run --example z_custom_message -- --mode status-pub
@@ -24,4 +64,6 @@ cargo run --example battery_state_sub # Receiving sensor_msgs
 cargo run --example z_srvcli          # Service example with example_interfaces
 ```
 
-See the [Networking](./networking.md) chapter for router setup details and alternative configurations.
+```admonish tip
+For a detailed walkthrough of creating your own project with ros-z (not using the repository examples), see the [Quick Start](./quick_start.md#option-2-create-your-own-project) guide.
+```

book/src/chapters/message_generation.md

@@ -14,8 +14,8 @@ graph LR
     B --> C[Parse & Resolve]
     C --> D[Type Hashing]
     D --> E[Code Generation]
-    E --> F[CDR Adapter]
-    E --> G[Protobuf Adapter]
+    E --> F[Rust Generator]
+    E --> G[Protobuf Generator]
     F --> H[Rust Structs + Traits]
     G --> I[Proto Files + Rust]
     H --> J[ros-z-msgs]
@@ -54,7 +54,7 @@ ros-z-codegen's orchestration capabilities:
 
 - Coordinates message discovery across sources
 - Manages build-time code generation
-- Provides serialization adapters
+- Provides code generators for different serialization formats
 - Generates ros-z-specific traits
 
 **Discovery workflow:**
@@ -82,16 +82,16 @@ sequenceDiagram
     B->>B: Generate Rust code
 ```
 
-### Serialization Adapters
+### Code Generators
 
-**CDR Adapter (default):**
+**Rust Generator (default):**
 
 - Generates structs with serde
-- CDR-compatible serialization
+- CDR-compatible serialization via ros-z-cdr
 - Full ROS 2 DDS interoperability
 - No additional dependencies
 
-**Protobuf Adapter (optional):**
+**Protobuf Generator (optional):**
 
 - Generates `.proto` files
 - Protobuf-compatible types