review

Author: YuanYuYuan

.github/workflows/docs.yml

@@ -2,33 +2,34 @@ name: Docs
 on: [push, pull_request]
 
 jobs:
-  test:
+  test_doc:
+    name: Test documentation
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: dtolnay/rust-toolchain@stable
-    - run: cargo build
-    - run: cargo test
-    - uses: peaceiris/actions-mdbook@v1
-      with:
-        mdbook-version: '0.4.40'
-    - run: mdbook test book -L ./target/debug/deps
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo build
+      - uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.40'
+      - run: mdbook test book -L ./target/debug/deps
 
-  publish:
+  publish_doc:
+    name: Publish to GitHub Pages
     if: github.ref == 'refs/heads/main'
-    needs: test
+    needs: test_doc
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
-    - uses: actions/checkout@v4
-    - uses: dtolnay/rust-toolchain@stable
-    - run: cargo build
-    - uses: peaceiris/actions-mdbook@v1
-      with:
-        mdbook-version: '0.4.40'
-    - run: mdbook build book
-    - uses: peaceiris/actions-gh-pages@v4
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./book/book
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo build
+      - uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.40'
+      - run: mdbook build book
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book

.github/workflows/semantic-pr.yml

@@ -19,7 +19,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          # Configure which types are allowed (https://github.com/commitizen/conventional-commit-types)
+          # Types (https://github.com/commitizen/conventional-commit-types)
           types: |
             fix
             feat

README.md

@@ -6,215 +6,50 @@
 
 ## Overview
 
-ROS 2 was designed to be independent from the underlying communication
-middleware. This is a nice architectural property, yet it does not come for
-free.  What if we were to streamline ROS 2 and implement it natively on Zenoh?
-ROS-Z, a Zenoh-native ROS 2 stack, answers this question. ROS-Z preserves
-portability for RCL-C/CPP/Py-based applications and provides an extremely
-optimised stack for Rust users that interoperates with any Zenoh RMW-based
-ROS 2.
+**ROS-Z** is a Zenoh-native ROS 2 stack that:
 
-![architecture](./assets/architecture.png)
-
-## Goals
+- Provides a pure-Rust ROS 2 implementation built directly on Zenoh
+- Preserves portability for RCL-C/CPP/Py-based applications
+- Delivers optimized performance for Rust users
+- Interoperates seamlessly with Zenoh RMW-based ROS 2
 
-**ROS-Z** was started as an experiment to understand what we could gain from
-verticalisation while at the same time providing (1) a pure-Rust stack to ROS2
-users, and (2) zenoh-native implementation of RCL-C. We hope that the lesson
-learned through this experiment will help the ROS community making ROS 2 even
-better.
+![architecture](./assets/architecture.png)
 
 ## Status
 
-**ROS-Z** is experimental software. It is tested with ROS 2 Jazzy and should
-be interoperable with ROS 2 Rolling, but we make no guarantees with respect to
-official distributions.
-
-## Documentation
-
-Comprehensive documentation with examples is available:
+**ROS-Z** is experimental software. It is tested with ROS 2 Jazzy and should be interoperable with ROS 2 Rolling, but we make no guarantees with respect to official distributions.
 
-- **Online**: [ros-z Documentation](https://zettascalelabs.github.io/ros-z/) (GitHub Pages)
-- **Local**: Build and view locally with `mdbook serve book` (see [book/README.md](book/README.md))
-
-The documentation includes:
-
-- Getting started guide
-- Publisher/subscriber examples
-- Service examples
-- Demo nodes compatible with ROS 2
-- API reference
-
-For contributing to the documentation, see [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## Building
-
-ROS-Z is designed to work without ROS dependencies by default.
-ROS-dependent features are opt-in.
-
-### Default Build (No ROS Dependencies)
-
-The default workspace build includes only the core library and works without
-ROS 2:
+## Quick Start
 
 ```bash
-# Build the workspace (ros-z + ros-z-codegen)
+# Build the core library (no ROS dependencies required)
 cargo build
 
 # Run tests
 cargo test
 
-# Build example with custom Rust-defined messages (no ros-z-msgs required)
-cargo build -p ros-z --example z_custom_message
-```
-
-### Building with ros-z-msgs (still no ROS required)
-
-The `ros-z-msgs` package includes bundled message definitions (std_msgs,
-geometry_msgs, sensor_msgs, nav_msgs) and can be built without ROS:
-
-```bash
-# Build ros-z-msgs with bundled messages (default, no ROS required)
-cargo build -p ros-z-msgs
-
-# Build examples that use bundled ros-z-msgs types
-cargo build -p ros-z --example z_pubsub       # Uses std_msgs
-cargo build -p ros-z --example z_pingpong     # Uses std_msgs
-cargo build -p ros-z --example twist_pub      # Uses geometry_msgs
-cargo build -p ros-z --example battery_state_sub  # Uses sensor_msgs
-cargo build -p ros-z --example laser_scan     # Uses sensor_msgs
-```
-
-### With ROS 2 Installation (Optional)
-
-Only needed for RCL bindings or external message packages not bundled with
-roslibrust:
-
-```bash
-# Build RCL bindings (requires ROS 2)
-cargo build -p rcl-z
-
-# Build ros-z-msgs with external message packages (requires ROS 2)
-cargo build -p ros-z-msgs --features external_msgs
-
-# Build example that uses external messages (requires ROS 2)
-cargo build --example z_srvcli --features external_msgs
-```
-
-### Using Nix (Optional)
-
-If you're using Nix, we provide development shells with all dependencies
-pre-configured:
-
-```bash
-# Default development environment (with ROS 2 Jazzy)
-nix develop
-
-# Specific ROS distros
-nix develop .#ros-jazzy      # ROS 2 Jazzy
-nix develop .#ros-rolling    # ROS 2 Rolling
-
-# Pure-Rust
-nix develop .#pureRust
-
-# CI environments (minimal, no dev tools)
-nix develop .#ros-jazzy-ci
-nix develop .#ros-rolling-ci
-nix develop .#pureRust-ci
+# Try an example
+cargo run --example z_pubsub
 ```
 
-**Note on `ros-z-msgs`:** This package can build without ROS installed! When
-ROS is not available, it automatically falls back to using bundled message
-definitions from the roslibrust git dependency. The build system searches for
-ROS packages in this order:
-
-1. System ROS installation (via `AMENT_PREFIX_PATH` or `CMAKE_PREFIX_PATH`)
-2. Common ROS installation paths (`/opt/ros/{rolling,jazzy,iron,humble}`)
-3. Roslibrust git dependency (`~/.cargo/git/checkouts/roslibrust-*/assets/`)
-
-This allows `ros-z-msgs` to generate message types even in environments without
-ROS 2 installed. The default `common_interfaces` feature includes `std_msgs`,
-`geometry_msgs`, and `sensor_msgs` which are all available in roslibrust
-assets. Note that `example_interfaces` is **not** included in the default build
-as it requires a ROS 2 installation.
-
-### Workspace Structure
-
-**Default workspace members** (no ROS dependencies):
-
-- **ros-z**: Core Zenoh-native ROS 2 library
-- **ros-z-codegen**: Message and service code generation utilities
-
-**Optional packages** (excluded from default build):
-
-- **ros-z-msgs**: Auto-generated ROS 2 message types (default features work
-  without ROS; external message packages require ROS 2)
-- **ros-z-tests**: Integration tests (requires ros-z-msgs)
-
-**ROS-dependent packages** (excluded from default build):
-
-- **rcl-z**: RCL C bindings (requires ROS 2 RCL libraries)
-
-### Examples
+See the [Quick Start Guide](https://zettascalelabs.github.io/ros-z/chapters/quick_start.html) for more details.
 
-Examples are categorized by their dependencies:
-
-- **Custom Rust messages** (no ros-z-msgs required):
-  - `z_custom_message` - Demonstrates pub/sub and service with custom
-    Rust-defined messages
-
-- **Bundled messages** (no ROS required, uses roslibrust assets):
-  - `z_pubsub` - Publisher/subscriber using std_msgs
-  - `z_pingpong` - Ping-pong latency benchmark using std_msgs
-  - `twist_pub` - Twist publisher using geometry_msgs
-  - `battery_state_sub` - Battery state subscriber using sensor_msgs
-  - `laser_scan` - Laser scan publisher using sensor_msgs
-
-- **External messages** (requires ROS 2 installation):
-  - `z_srvcli` - Service client/server using example_interfaces
-    - Build with: `cargo build --example z_srvcli --features external_msgs`
-
-- **Advanced** (requires protobuf feature):
-  - `protobuf_demo` - Demonstrates protobuf serialization with both ROS
-    messages and custom protobuf messages
-    - Build with: `cargo build -p protobuf_demo`
-
-## Feature Flags
-
-### ros-z
-
-- `protobuf` - Enable protobuf serialization support (requires `prost`)
-- `rcl-z` - Enable RCL integration features
-- `external_msgs` - Enable examples that require external ROS message packages
-  (propagates to `ros-z-msgs/external_msgs`)
-
-### ros-z-msgs
-
-Messages are organized into two categories:
-
-**Bundled messages** (no ROS installation required):
-
-- `bundled_msgs` (default) - All bundled message packages
-- `std_msgs`, `geometry_msgs`, `sensor_msgs`, `nav_msgs` - Individual bundled
-  packages
-- `common_interfaces` - Convenience feature for std_msgs, geometry_msgs,
-  sensor_msgs
-
-**External messages** (require ROS 2 installation):
+## Documentation
 
-- `external_msgs` - All external message packages
-- `example_interfaces` - Individual external package
+📚 **[Read the Book](https://zettascalelabs.github.io/ros-z/)** for comprehensive documentation including:
 
-**Other features**:
+- Installation and build instructions
+- Examples and tutorials
+- API reference
+- Feature flags and configuration
+- Contributing guidelines
 
-- `all_msgs` - Enable both bundled and external messages (requires ROS 2)
-- `protobuf` - Generate protobuf types (requires `ros-z/protobuf`)
+**Local Development:** `mdbook serve book`
 
-### ros-z-codegen
+## License
 
-- `protobuf` - Enable protobuf code generation support
+[View license](LICENSE)
 
-### ros-z-tests
+## Contributing
 
-- `ros-msgs` - Enable tests with ros-z-msgs dependency
-- `interop-tests` - ROS interoperability tests (requires `ros-msgs`)
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

book/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "ros-z-book"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+ros-z = { path = "../ros-z" }
+ros-z-msgs = { path = "../ros-z-msgs" }
+tokio = { version = "1.47.1", features = ["full"] }
+clap = { version = "4.5.45", features = ["derive"] }
+zenoh = { version = "1.6.2", default-features = false, features = [
+  "transport_tcp",
+  "transport_serial",
+] }
+csv = "1.3.1"
+anyhow = "1.0"
+tracing = "0.1.41"
+serde = "1.0.219"

book/src/SUMMARY.md

@@ -5,20 +5,23 @@
 # Getting Started
 
 - [Quick Start](./chapters/quick_start.md)
+- [Building](./chapters/building.md)
 
 # Core Concepts
 
 - [Publishers and Subscribers](./chapters/pubsub.md)
   - [Simple Publisher](./chapters/simple_pub.md)
   - [Simple Subscriber](./chapters/simple_sub.md)
-  - [Custom Messages](./chapters/custom_messages.md)
 - [Services](./chapters/services.md)
   - [Service Server](./chapters/service_server.md)
   - [Service Client](./chapters/service_client.md)
 - [Actions](./chapters/actions.md)
+- [Message Generation](./chapters/message_generation.md)
+  - [Custom Messages](./chapters/custom_messages.md)
 
 # Examples
 
+- [Overview](./chapters/examples_overview.md)
 - [Demo Nodes](./chapters/demo_nodes.md)
   - [Talker](./chapters/demo_talker.md)
   - [Listener](./chapters/demo_listener.md)
@@ -30,7 +33,5 @@
   - [Laser Scan](./chapters/laser_scan.md)
   - [Zenoh PingPong](./chapters/z_pingpong.md)
 
-# Reference
-
-- [API Documentation](./chapters/api_reference.md)
-- [Contributing](./chapters/contributing.md)
+- [Feature Flags](./chapters/feature_flags.md)
+- [Troubleshooting](./chapters/troubleshooting.md)

book/src/chapters/battery_state_sub.md

@@ -4,7 +4,7 @@ This example demonstrates subscribing to battery status messages.
 
 ## Complete Example
 
-```rust,no_run
+```rust,ignore
 {{#include ../../../ros-z/examples/battery_state_sub.rs}}
 ```