docs: improve documentation and add automated testing

[YuanYuYuan]

Summary

Improves documentation with enhanced quick start guide, comprehensive router installation instructions, automated validation tools, and updated terminology to match codebase architecture.

Key Changes

Enhanced Documentation

Quick Start Guide - Restructured with two-path approach:

• Try Examples: Clone repository and run pre-built examples
• Create Your Own Project: Step-by-step guide for creating new projects from scratch
• Simplified router installation options with direct link to releases page

Networking Guide - Major improvements:

• Added architecture diagram showing router-based discovery and peer-to-peer communication
• Comprehensive router installation section with 6 methods
• Comparison table evaluating setup speed and requirements
• Platform-specific instructions for Linux, macOS, and Windows
• Updated to use releases page link instead of hardcoded download URLs

Examples Guide - Improved structure:

• Clear separation between repository examples vs. standalone projects
• Quick router installation reference
• Fixed nested code fence issues for proper mdbook testing

Message Generation - Updated terminology:

• Changed "Adapter" to "Generator" throughout documentation
• Updated diagrams to reflect current architecture
• Renamed section from "Serialization Adapters" to "Code Generators"
• Matches actual codebase structure (ProtobufMessageGenerator, etc.)

Fixed Installation Bug

Issue: cargo install zenoh fails with error:

error: there is nothing to install in `zenoh v1.7.2`, because it has no binaries

Fix: Changed to cargo install zenohd in all documentation files.

Impact: Users can now successfully install the Zenoh router using documented commands.

Code Cleanup

Renamed legacy file for consistency:

• protobuf_adapter.rs → protobuf_generator.rs
• Updated module imports in lib.rs
• Matches struct name ProtobufMessageGenerator and generator module pattern

Fixed documentation paths:

• Updated include paths from ros-z/examples/ to crates/ros-z/examples/
• Fixes broken includes after workspace reorganization

Documentation Automation Scripts

Added 4 new Nushell scripts to prevent doc/code drift:

check-example-coverage.nu

• Scans all examples in crates
• Reports which examples are documented
• Current coverage: 41% (11/27 examples)

extract-help.nu

• Extracts --help output from all Clap-based examples
• Generates structured JSON with commands, options, and descriptions
• Enables automated CLI documentation validation

validate-cli-docs.nu

• Validates documented CLI commands match actual --help output
• Checks for missing examples, outdated syntax, incorrect arguments
• Can auto-generate skeleton documentation for missing examples

test-example-docs.nu

• End-to-end testing of example documentation
• Validates examples mentioned in docs can actually run
• Ensures code snippets stay up-to-date

Pre-commit Integration

Added to nix/pre-commit.nix:

• mdbook-build - Validates documentation builds successfully

  • Triggers on markdown and TOML changes in book/
  • Catches broken includes, invalid syntax, missing files

• mdbook-test - Tests that code examples compile

  • Triggers on markdown changes in book/ or example code changes
  • Catches outdated code examples and compilation errors

Benefits:

• Prevents broken documentation from being committed
• Ensures code examples stay synchronized with codebase
• Catches terminology drift automatically

Demo Nodes Improvements

Added --help support to all 6 demo nodes:

• talker, listener
• add_two_ints_client, add_two_ints_server
• fibonacci_action_client, fibonacci_action_server

Enables better CLI documentation validation and improved user experience.

CI Integration

Updated .github/workflows/docs.yml to run example coverage check on documentation builds.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-02-09 12:17 UTC