add mdbook

Author: YuanYuYuan

.github/workflows/docs.yml

@@ -33,3 +33,5 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./book/book
+          clean_exclude: pr-preview/
+          force_orphan: false

.github/workflows/pr-preview.yml

@@ -0,0 +1,51 @@
+name: PR Preview
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+concurrency:
+  group: preview-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        if: github.event.action != 'closed'
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Build project
+        if: github.event.action != 'closed'
+        run: cargo build
+
+      - name: Setup mdBook
+        if: github.event.action != 'closed'
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.40'
+
+      - name: Install mdbook-admonish
+        if: github.event.action != 'closed'
+        run: cargo install mdbook-admonish
+
+      - name: Install mdbook-mermaid
+        if: github.event.action != 'closed'
+        run: cargo install mdbook-mermaid
+
+      - name: Build mdBook
+        if: github.event.action != 'closed'
+        run: mdbook build book
+
+      - name: Deploy Preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./book/book
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview

.gitignore

@@ -10,3 +10,5 @@ result*
 
 # mdBook build output
 /book/book/
+/book/*.js
+/book/*.css

book/book.toml

@@ -12,11 +12,20 @@ edition = "2024"
 [build]
 build-dir = "book"
 
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.1.0" # do not edit: managed by `mdbook-admonish install`
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
 [output.html]
 default-theme = "light"
 preferred-dark-theme = "navy"
 git-repository-url = "https://github.com/ZettaScaleLabs/ros-z"
 edit-url-template = "https://github.com/ZettaScaleLabs/ros-z/edit/main/{path}"
+additional-css = ["mdbook-admonish.css", "book/mdbook-admonish.css"]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
 
 [output.html.fold]
 enable = true

book/src/chapters/actions.md

@@ -1,42 +1,150 @@
 # Actions
 
-Actions provide a mechanism for long-running tasks in ROS 2, with the ability to:
+**Actions enable long-running tasks with progress feedback and cancellation support, perfect for operations that take seconds or minutes to complete.** Unlike services that return immediately, actions provide streaming feedback while executing complex workflows.
 
-- Send goals to an action server
-- Receive feedback during execution
-- Cancel goals in progress
-- Get final results
+```admonish tip
+Use actions for robot navigation, trajectory execution, or any operation where you need progress updates and the ability to cancel mid-execution. Use services for quick request-response operations.
+```
 
-## Overview
+## Action Lifecycle
 
-Actions are useful for tasks that:
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Accepted: Send Goal
+    Accepted --> Executing: Start Processing
+    Executing --> Executing: Send Feedback
+    Executing --> Succeeded: Complete
+    Executing --> Canceled: Cancel Request
+    Executing --> Aborted: Error Occurs
+    Succeeded --> [*]
+    Canceled --> [*]
+    Aborted --> [*]
+```
 
-- Take a long time to complete
-- Need to provide progress updates
-- May need to be cancelled
+## Components
 
-Common examples include:
+| Component | Type | Purpose |
+|-----------|------|---------|
+| **Goal** | Input | Defines the desired outcome |
+| **Feedback** | Stream | Progress updates during execution |
+| **Result** | Output | Final outcome when complete |
+| **Status** | State | Current execution state |
 
-- Navigation to a goal
-- Gripper control
-- Long computations
+## Communication Pattern
 
-## Components
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+
+    C->>S: Send Goal
+    S->>C: Goal Accepted
+    loop During Execution
+        S->>C: Feedback Update
+    end
+    alt Success
+        S->>C: Result (Success)
+    else Canceled
+        C->>S: Cancel Request
+        S->>C: Result (Canceled)
+    else Error
+        S->>C: Result (Aborted)
+    end
+```
+
+## Use Cases
+
+**Robot Navigation:**
+
+- Goal: Target position and orientation
+- Feedback: Current position, distance remaining, obstacles detected
+- Result: Final position, success/failure reason
+
+**Gripper Control:**
+
+- Goal: Desired grip force and position
+- Feedback: Current force, contact detection
+- Result: Grip achieved, object secured
+
+**Long Computations:**
+
+- Goal: Computation parameters
+- Feedback: Progress percentage, intermediate results
+- Result: Final computed value, execution time
+
+```admonish info
+Actions excel when operations take more than a few seconds and users need visibility into progress. For sub-second operations, prefer services for simplicity.
+```
+
+## Implementation Status
+
+```admonish note
+Action support in ros-z is under active development. The core infrastructure is in place, and examples are available in the repository. Check the latest API documentation for implementation details.
+```
+
+## Example Patterns
+
+**Action Server:**
+
+```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)
+    })?;
+}
+```
+
+**Action Client:**
+
+```rust,ignore
+let action_client = node
+    .create_action_client::<Fibonacci>("/fibonacci")
+    .build()?;
+
+let goal_handle = action_client.send_goal(GoalMsg {
+    order: 10
+}).await?;
+
+while let Some(feedback) = goal_handle.feedback().await {
+    println!("Progress: {}", feedback.current);
+}
 
-An action consists of:
+let result = goal_handle.get_result().await?;
+println!("Final: {:?}", result.sequence);
+```
 
-1. **Goal**: The desired outcome
-2. **Feedback**: Progress updates during execution
-3. **Result**: The final outcome
+```admonish warning
+Always implement timeout mechanisms for action clients. Long-running actions can fail or hang, and clients need graceful degradation strategies.
+```
 
-## Implementation
+## Comparison with Other Patterns
 
-Action support in ros-z is under active development. Check the examples directory and API documentation for the latest implementation details.
+| Pattern | Duration | Feedback | Cancellation | Use Case |
+|---------|----------|----------|--------------|----------|
+| **Pub-Sub** | Continuous | No | N/A | Sensor data streaming |
+| **Service** | < 1 second | No | No | Quick queries |
+| **Action** | Seconds to minutes | Yes | Yes | Long-running tasks |
 
-## Example Use Cases
+## Resources
 
-- Robot navigation with progress updates
-- Trajectory execution with real-time feedback
-- Complex multi-step operations
+- **[ROS 2 Actions Documentation](https://docs.ros.org/en/rolling/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.html)** - Official ROS 2 action guide
+- **[ros-z Examples](https://github.com/ZettaScaleLabs/ros-z/tree/main/ros-z/examples)** - Working action implementations
+- **[Services](./services.md)** - Simpler request-response pattern
 
-For concrete examples, see the ros-z examples directory.
+**Action implementation is evolving. Check the ros-z repository for the latest examples and API updates.**