Add docs for control.ros.org (backport #346) (#353)

mergify[bot] · christophfroehlich · web-flow · commit dae75f48410e · 2025-06-11T14:56:05.000+02:00
Co-authored-by: Christoph Froehlich &lt;christoph.froehlich@ait.ac.at&gt;
Co-authored-by: Christoph Fröhlich &lt;christophfroehlich@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -5,14 +5,14 @@ realtime_tools
 
 Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
 
-Some documentation can be found at [docs.ros.org](http://docs.ros.org/en/rolling/p/realtime_tools/doc/index.html).
+Further documentation can be found at [docs.ros.org](https://control.ros.org/rolling/doc/realtime_tools/doc/index.html).
 
 ## Contributing
 As an open-source project, we welcome each contributor, regardless of their background and experience. Pick a [PR](https://github.com/ros-controls/realtime_tools/pulls) and review it, or [create your own](https://github.com/ros-controls/realtime_tools/contribute)!
 If you are new to the project, please read the [contributing guide](https://control.ros.org/rolling/doc/contributing/contributing.html) for more information on how to get started. We are happy to help you with your first contribution.
 
 ## Build status
-ROS2 Distro | Branch | Build status | Documentation | Package Build
+ROS2 Distro | Branch | Build status | API Documentation | Package Build
 :---------: | :----: | :----------: | :-----------: | :---------------:
 **Rolling** | [`master`](https://github.com/ros-controls/realtime_tools/tree/master) | [![Binary Build](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-binary-build.yml/badge.svg?branch=master)](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-binary-build.yml?branch=master) <br> [![Source Build](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-source-build.yml/badge.svg?branch=master)](https://github.com/ros-controls/realtime_tools/actions/workflows/rolling-source-build.yml?branch=master) <br> [![build.ros2.org](https://build.ros2.org/buildStatus/icon?job=Rdev__realtime_tools__ubuntu_noble_amd64&subject=build.ros2.org)](https://build.ros2.org/job/Rdev__realtime_tools__ubuntu_noble_amd64/) | [API](http://docs.ros.org/en/rolling/p/realtime_tools/) | [![Build Status](https://build.ros2.org/buildStatus/icon?job=Rbin_uN64__realtime_tools__ubuntu_noble_amd64__binary)](https://build.ros2.org/job/Rbin_uN64__realtime_tools__ubuntu_noble_amd64__binary/)
 **Kilted** | [`master`](https://github.com/ros-controls/realtime_tools/tree/master) | see above <br> [![build.ros2.org](https://build.ros2.org/buildStatus/icon?job=Kdev__realtime_tools__ubuntu_noble_amd64&subject=build.ros2.org)](https://build.ros2.org/job/Kdev__realtime_tools__ubuntu_noble_amd64/) | [API](http://docs.ros.org/en/rolling/p/realtime_tools/) | [![Build Status](https://build.ros2.org/buildStatus/icon?job=Kbin_uN64__realtime_tools__ubuntu_noble_amd64__binary)](https://build.ros2.org/job/Kbin_uN64__realtime_tools__ubuntu_noble_amd64__binary/)
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,59 +1,8 @@
-Welcome to the documentation for realtime_tools
-===============================================
+:github_url: https://github.com/ros-controls/realtime_tools/blob/{REPOS_FILE_BRANCH}/doc/index.rst
 
-Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
-
-For more information of the ros2_control framework see `control.ros.org <https://control.ros.org/>`__.
-
-Realtime Publisher
-------------------
-The ``realtime_tools::RealtimePublisher`` allows users that write C++ ros2_controllers to publish messages on a ROS topic from a hard realtime loop. The normal ROS publisher is not realtime safe, and should not be used from within the update loop of a realtime controller. The realtime publisher is a wrapper around the ROS publisher; the wrapper creates an extra non-realtime thread that publishes messages on a ROS topic. The example below shows a typical usage of the realtime publisher in the ``on_configure()`` (non-realtime method) and ``update()`` (realtime method) methods of a realtime controller:
-
-.. code-block:: cpp
-
-  #include <realtime_tools/realtime_publisher.h>
-
-  class MyController : public controller_interface::ControllerInterface
-  {
-  ...
-  private:
-    std::shared_ptr<realtime_tools::RealtimePublisher<my_msgs::msg::MyMsg>> state_publisher_;
-    std::shared_ptr<rclcpp::Publisher<my_msgs::msg::MyMsg>> s_publisher_;
-  }
-
-  controller_interface::CallbackReturn MyController::on_configure(
-    const rclcpp_lifecycle::State & /*previous_state*/)
-  {
-    ...
-    s_publisher_ = get_node()->create_publisher<my_msgs::msg::MyMsg>(
-      "~/status", rclcpp::SystemDefaultsQoS());
-    state_publisher_ =
-      std::make_unique<realtime_tools::RealtimePublisher<ControllerStateMsg>>(s_publisher_);
-    ...
-  }
+realtime_tools
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  controller_interface::return_type MyController::update(
-    const rclcpp::Time & /*time*/, const rclcpp::Duration & /*period*/)
-  {
-    ...
-    // Publish controller state
-    state_publisher_->lock();
-    state_publisher_->msg_ = some_msg;
-    state_publisher_->unlockAndPublish();
-  }
-
-
-API documentation
-------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   C++ API <generated/index>
-
-
-Indices and Search
-==================
+Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
 
-* :ref:`genindex`
-* :ref:`search`
+.. include:: ../realtime_tools/doc/realtime_publisher.rst
diff --git a/doc/migration.rst b/doc/migration.rst
@@ -0,0 +1,9 @@
+:github_url: https://github.com/ros-controls/realtime_tools/blob/{REPOS_FILE_BRANCH}/doc/migration.rst
+
+Migration Guides: Jazzy to Kilted
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This list summarizes important changes between Jazzy (previous) and Kilted (current) releases, where changes to user code might be necessary.
+
+RealtimeBox
+*******************************
+* ``RealtimeBox`` is deprecated. Update your code to use ``realtime_thread_safe_box.hpp`` header, and class name ``RealtimeThreadSafeBox`` instead. (`#318 <https://github.com/ros-controls/realtime_tools/pull/318>`__, `#342 <https://github.com/ros-controls/realtime_tools/pull/342>`__).
diff --git a/doc/release_notes.rst b/doc/release_notes.rst
@@ -0,0 +1,9 @@
+:github_url: https://github.com/ros-controls/realtime_tools/blob/{REPOS_FILE_BRANCH}/doc/release_notes.rst
+
+Release Notes: Jazzy to Kilted
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This list summarizes the changes between Jazzy (previous) and Kilted (current) releases.
+
+RealtimeBox
+*******************************
+* ``RealtimeBox`` got renamed to ``RealtimeThreadSafeBox`` and uses real-time mutexes now (`#318 <https://github.com/ros-controls/realtime_tools/pull/318>`__, `#342 <https://github.com/ros-controls/realtime_tools/pull/342>`__).
diff --git a/realtime_tools/doc/conf.py b/realtime_tools/doc/conf.py
diff --git a/realtime_tools/doc/index.rst b/realtime_tools/doc/index.rst
@@ -0,0 +1,23 @@
+Welcome to the documentation for realtime_tools
+===============================================
+
+Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
+
+For more information of the ros2_control framework see `control.ros.org <https://control.ros.org/>`__.
+
+.. include:: realtime_publisher.rst
+
+API documentation
+------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   C++ API <generated/index>
+
+
+Indices and Search
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/realtime_tools/doc/realtime_publisher.rst b/realtime_tools/doc/realtime_publisher.rst
@@ -0,0 +1,36 @@
+Realtime Publisher
+------------------
+The ``realtime_tools::RealtimePublisher`` allows users that write C++ ros2_controllers to publish messages on a ROS topic from a hard realtime loop. The normal ROS publisher is not realtime safe, and should not be used from within the update loop of a realtime controller. The realtime publisher is a wrapper around the ROS publisher; the wrapper creates an extra non-realtime thread that publishes messages on a ROS topic. The example below shows a typical usage of the realtime publisher in the ``on_configure()`` (non-realtime method) and ``update()`` (realtime method) methods of a realtime controller:
+
+.. code-block:: cpp
+
+  #include <realtime_tools/realtime_publisher.hpp>
+
+  class MyController : public controller_interface::ControllerInterface
+  {
+  ...
+  private:
+    std::shared_ptr<realtime_tools::RealtimePublisher<my_msgs::msg::MyMsg>> state_publisher_;
+    std::shared_ptr<rclcpp::Publisher<my_msgs::msg::MyMsg>> s_publisher_;
+  }
+
+  controller_interface::CallbackReturn MyController::on_configure(
+    const rclcpp_lifecycle::State & /*previous_state*/)
+  {
+    ...
+    s_publisher_ = get_node()->create_publisher<my_msgs::msg::MyMsg>(
+      "~/status", rclcpp::SystemDefaultsQoS());
+    state_publisher_ =
+      std::make_unique<realtime_tools::RealtimePublisher<ControllerStateMsg>>(s_publisher_);
+    ...
+  }
+
+  controller_interface::return_type MyController::update(
+    const rclcpp::Time & /*time*/, const rclcpp::Duration & /*period*/)
+  {
+    ...
+    // Publish controller state
+    state_publisher_->lock();
+    state_publisher_->msg_ = some_msg;
+    state_publisher_->unlockAndPublish();
+  }
