docs(readme): improve formatting and add installation workarounds (#589)

- Fix markdown heading formatting to use proper ## syntax
- Add workaround instructions for issue #557 with required packages
- Add missing dependency clones for rosidl_core and rosidl_defaults

Signed-off-by: Esteve Fernandez <esteve@apache.org>

Author: esteve

README.md

@@ -6,24 +6,22 @@ ROS 2 for Rust
 [![Win CI Status](https://github.com/ros2-rust/ros2_rust/actions/workflows/rust-win.yml/badge.svg?branch=main)](https://github.com/ros2-rust/ros2_rust/actions/workflows/rust-win.yml)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Introduction
-------------
+## Introduction
 
-This is a set of projects (the `rclrs` client library, code generator, examples and more) that
+This is a set of projects (the `rclrs` client library, code generator, examples, and more) that
 enables developers to write ROS 2 applications in Rust.
 
-Features and limitations
-------------------------
+## Features and Limitations
 
-The current set of features include:
+The current set of features includes:
 - Message generation with support for all ROS message types
 - Publishers and subscriptions (including async variants)
 - Loaned messages (zero-copy messaging)
 - Dynamic message handling (runtime message introspection and manipulation)
 - Tunable QoS settings
 - Clients and services (including async variants)
 - Actions (action servers and clients with async support)
-- Timers (repeating, oneshot, and inert timers)
+- Timers (repeating, one-shot, and inert timers)
 - Parameters (mandatory, optional, and read-only with parameter services)
 - Logging with ROS-compliant logging utilities and rosout support
 - Graph queries (topic/node discovery, endpoint information)
@@ -36,8 +34,7 @@ Some things are still missing however, see the [issue list](https://github.com/r
 
 Since the client library is still rapidly evolving, there are no stability guarantees for the moment.
 
-Installation
-------------
+## Installation
 
 ### Prerequisites
 
@@ -54,27 +51,48 @@ sudo apt install -y git libclang-dev python3-pip python3-vcstool
 pip install --break-system-packages colcon-cargo colcon-ros-cargo
 ```
 
-### All ROS distributions
+Because of an issue in `rclrs` (https://github.com/ros2-rust/ros2_rust/issues/557), as a workaround, the following two packages need to be installed:
 
-`rclrs` is released on [crates.io](https://crates.io/crates/rclrs), you can add it to your project directly:
+```shell
+# Install workaround packages
+sudo apt install -y ros-$ROS_DISTRO-example-interfaces
+sudo apt install -y ros-$ROS_DISTRO-test-msgs
+```
+
+### All ROS Distributions
+
+`rclrs` is released on [crates.io](https://crates.io/crates/rclrs) and you can add it to your project directly:
 
 ```toml
 [dependencies]
 rclrs = "0.7"
 ```
 
 Due to different ROS 2 distributions having different levels of integration with `rclrs`, if you'd like to
-build and run the examples, please follow the according section.
+build and run the examples, please follow the corresponding section.
 
 ### ROS 2 Lyrical Luth and Rolling
 
-To run the examples, install the `test_msgs` and `example_interfaces` packages,
-clone the examples repository to your workspace and build:
+To run the examples, install the `test_msgs` and `example_interfaces` packages, clone the examples repository to your workspace, and build:
 
 ```shell
 sudo apt install -y ros-rolling-example-interfaces ros-rolling-test-msgs
 mkdir -p workspace/src && cd workspace
 git clone https://github.com/ros2-rust/examples.git src/examples
+```
+
+Temporarily (as of 2025-01-21), the `rosidl_rust` repository which contains the code generator needs to be cloned as well:
+
+```shell
+mkdir -p workspace/src && cd workspace
+git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
+```
+
+The above commands can be removed once an updated version of the generator is shipped with the next ROS 2 sync.
+
+Build the workspace:
+
+```shell
 . /opt/ros/rolling/setup.sh  # Or source your ROS 2 installation
 colcon build
 ```
@@ -88,9 +106,19 @@ mkdir -p workspace/src && cd workspace
 git clone -b kilted https://github.com/ros2/common_interfaces.git src/common_interfaces
 git clone -b kilted https://github.com/ros2/example_interfaces.git src/example_interfaces
 git clone -b kilted https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
+git clone -b kilted https://github.com/ros2/rosidl_core.git src/rosidl_core
+git clone -b kilted https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
 git clone -b kilted https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
 ```
 
+Temporarily (as of 2025-01-21), the `rosidl_rust` repository which contains the code generator needs to be cloned as well:
+
+```shell
+git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
+```
+
+The above command can be removed once an updated version of the generator is shipped with the next ROS 2 sync.
+
 Build the workspace:
 
 ```shell
@@ -104,11 +132,13 @@ For ROS 2 Jazzy, you need to clone the code generator and message packages to yo
 
 ```shell
 mkdir -p workspace/src && cd workspace
-git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
 git clone -b jazzy https://github.com/ros2/common_interfaces.git src/common_interfaces
 git clone -b jazzy https://github.com/ros2/example_interfaces.git src/example_interfaces
 git clone -b jazzy https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
+git clone -b jazzy https://github.com/ros2/rosidl_core.git src/rosidl_core
+git clone -b jazzy https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
 git clone -b jazzy https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
+git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
 git clone https://github.com/ros2-rust/examples.git src/examples
 ```
 
@@ -126,11 +156,13 @@ For ROS 2 Humble, you need to clone the code generator and message packages to y
 
 ```shell
 mkdir -p workspace/src && cd workspace
-git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
 git clone -b humble https://github.com/ros2/common_interfaces.git src/common_interfaces
 git clone -b humble https://github.com/ros2/example_interfaces.git src/example_interfaces
 git clone -b humble https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
+git clone -b humble https://github.com/ros2/rosidl_core.git src/rosidl_core
+git clone -b humble https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
 git clone -b humble https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
+git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
 git clone https://github.com/ros2-rust/examples.git src/examples
 ```
 
@@ -153,7 +185,8 @@ ros2 run examples_rclrs_minimal_pub_sub minimal_publisher
 . ./install/setup.sh
 ros2 run examples_rclrs_minimal_pub_sub minimal_subscriber
 ```
-or
+
+Or:
 
 ```shell
 # In a new terminal (or tmux window)
@@ -163,6 +196,7 @@ ros2 launch examples_rclrs_minimal_pub_sub minimal_pub_sub.launch.xml
 
 For detailed building instructions and additional setup options, see the [in-depth guide](docs/building.md).
 
-Further documentation articles:
+## Further Documentation
+
 - [Tutorial on writing your first node with `rclrs`](docs/writing-your-first-rclrs-node.md)
 - [Contributor's guide](docs/CONTRIBUTING.md)