From 9f0db26a62d35a4d385ba68551f52f0cbd56e69d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Fr=C3=B6hlich?= Date: Wed, 17 Apr 2024 15:33:47 +0200 Subject: [PATCH] Add custom rosdoc2 config (#161) Co-authored-by: Felix Exner (fexner) --- .github/workflows/rosdoc2.yml | 16 ++++++++++ .pre-commit-config.yaml | 2 ++ README.md | 1 + doc.dox | 13 -------- doc/conf.py | 5 +++ doc/index.rst | 59 +++++++++++++++++++++++++++++++++++ package.xml | 2 +- 7 files changed, 84 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/rosdoc2.yml delete mode 100644 doc.dox create mode 100644 doc/conf.py create mode 100644 doc/index.rst diff --git a/.github/workflows/rosdoc2.yml b/.github/workflows/rosdoc2.yml new file mode 100644 index 00000000..06e67d5f --- /dev/null +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f7dd66fa..b37e12f9 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/README.md b/README.md index 6564534b..1c0a65f7 100644 --- a/README.md +++ b/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 diff --git a/doc.dox b/doc.dox deleted file mode 100644 index b602b972..00000000 --- a/doc.dox +++ /dev/null @@ -1,13 +0,0 @@ -/** -@mainpage - -@htmlinclude manifest.html - -Realtime Tools - -@section cpp The C++ API - - - realtime_tools::RealtimePublisher - - -**/ diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..b6134e9a --- /dev/null +++ b/doc/conf.py @@ -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" diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..8a05cc73 --- /dev/null +++ b/doc/index.rst @@ -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 `__. + +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 + + class MyController : public controller_interface::ControllerInterface + { + ... + private: + std::shared_ptr> state_publisher_; + std::shared_ptr> s_publisher_; + } + + controller_interface::CallbackReturn MyController::on_configure( + const rclcpp_lifecycle::State & /*previous_state*/) + { + ... + s_publisher_ = get_node()->create_publisher( + "~/status", rclcpp::SystemDefaultsQoS()); + state_publisher_ = + std::make_unique>(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 + + +Indices and Search +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/package.xml b/package.xml index 2ef269e6..7658c857 100644 --- a/package.xml +++ b/package.xml @@ -8,7 +8,7 @@ 3-Clause BSD - http://ros.org/wiki/realtime_tools + https://control.ros.org https://github.com/ros-controls/realtime_tools/issues https://github.com/ros-controls/realtime_tools/