Add custom launch file and timing issues info to Docs

doc/index.rst

@@ -400,3 +400,78 @@ This uses the effort command interface for the cart's degree of freedom on the r
 
   ros2 launch gz_ros2_control_demos pendulum_example_position.launch.py
   ros2 run gz_ros2_control_demos example_position
+
+
+Creating a Custom Launch File
+=============================
+
+To get started with your own launch file using `gz_ros2_control`, refer to the example launch files in the repository:
+
+`Example launch files <https://github.com/ros-controls/gz_ros2_control/tree/rolling/gz_ros2_control_demos/launch>`_
+
+Basic Elements
+--------------
+
+1. **Launching the Gazebo simulator**
+
+You can use the ``gz_sim.launch.py`` file provided by ``gz_ros2_control`` to launch Gazebo. Here's an example:
+
+.. code-block:: python
+
+    gz_sim = IncludeLaunchDescription(
+        PythonLaunchDescriptionSource(gz_sim_launch),
+        launch_arguments={
+            'gz_args': ['-r -v4 empty.sdf'],
+            'on_exit_shutdown': 'true'
+        }.items()
+    )
+
+Explanation of flags:
+
+- ``-r``: Starts the simulator immediately.
+- ``-v4``: Sets the logging verbosity to level 4.
+
+2. **Launching the ros_gz_bridge and publishing the `/clock` topic**
+
+It is essential to publish the ``/clock`` topic for the ``controller_manager`` to function correctly:
+
+.. code-block:: python
+
+    gz_bridge = Node(
+        package="ros_gz_bridge",
+        executable="parameter_bridge",
+        arguments=['/clock@rosgraph_msgs/msg/Clock[gz.msgs.Clock'],
+        parameters=[{
+            "qos_overrides./tf_static.publisher.durability": "transient_local"
+        }],
+        output="screen",
+    )
+
+.. warning::
+
+   If you **do not** publish the ``/clock`` topic, the ``controller_manager`` will issue warnings or errors such as:
+
+   .. code-block:: console
+
+      [gazebo-1] [WARN] [1744219953.983130822] [controller_manager]: No clock received, using time argument instead! Check your node's clock configuration (use_sim_time parameter) and if a valid clock source is available.
+
+Timing Issues
+-------------
+
+By default, the ``controller_manager`` launched by ``gz_ros2_control`` has ``use_sim_time=true``. If for any reason this is set to ``false``, it will fall back to the system clock.
+
+This results in logs like:
+
+.. code-block:: console
+
+    [gazebo-1] [INFO] [1744209678.974210234] [gz_ros_control]: Loading controller_manager
+    [gazebo-1] [INFO] [1744209679.000651931] [controller_manager]: Using Steady (Monotonic) clock for triggering controller manager cycles.
+
+Eventually leading to a fatal error:
+
+.. code-block:: console
+
+    [gazebo-1] terminate called after throwing an instance of 'std::runtime_error'
+    [gazebo-1]   what():  can't compare times with different time sources
+
+Ensure ``use_sim_time`` is correctly set to ``true`` when working with simulation time to avoid such mismatches.