Add custom rosdoc2 config (#161)

Co-authored-by: Felix Exner (fexner) <[email protected]>

Author: christophfroehlich

.github/workflows/rosdoc2.yml

@@ -0,0 +1,16 @@
+name: rosdoc2
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - doc/**
+      - rosdoc2.yaml
+      - package.xml
+
+
+jobs:
+  check:
+    uses: ros-controls/ros2_control_ci/.github/workflows/reusable-rosdoc2.yml@master

.pre-commit-config.yaml

@@ -26,6 +26,7 @@ repos:
       - id: check-symlinks
       - id: check-xml
       - id: check-yaml
+        exclude: rosdoc2.yaml
       - id: debug-statements
       - id: end-of-file-fixer
       - id: mixed-line-ending
@@ -105,6 +106,7 @@ repos:
         description: Check if copyright notice is available in all files.
         entry: ament_copyright
         language: system
+        exclude: doc/conf.py
 
   # Docs - RestructuredText hooks
   - repo: https://github.com/PyCQA/doc8

README.md

@@ -3,6 +3,7 @@ realtime_tools
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![codecov](https://codecov.io/gh/ros-controls/realtime_tools/branch/master/graph/badge.svg?token=Osge1FOaAh)](https://app.codecov.io/gh/ros-controls/realtime_tools/tree/master)
 
+Contains a set of tools that can be used from a hard realtime thread, without breaking the realtime behavior.
 
 ## Build status
 ROS2 Distro | Branch | Build status | Documentation | Released packages

doc.dox

@@ -0,0 +1,5 @@
+# Configuration file for the Sphinx documentation builder.
+# settings will be overridden by rosdoc2, so we add here only custom settings
+
+copyright = "2024, ros2_control development team"
+html_logo = "https://control.ros.org/master/_static/logo_ros-controls.png"

doc/conf.py

@@ -0,0 +1,59 @@
+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/>`__.
+
+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_);
+    ...
+  }
+
+  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
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/index.rst

@@ -8,7 +8,7 @@
 
   <license>3-Clause BSD</license>
 
-  <url type="website">http://ros.org/wiki/realtime_tools</url>
+  <url type="website">https://control.ros.org</url>
   <url type="bugtracker">https://github.com/ros-controls/realtime_tools/issues</url>
   <url type="repository">https://github.com/ros-controls/realtime_tools/</url>