Add custom rosdoc2 config for ros2_controllers metapackage (#1100)

* Add simple rosdoc2 landing page

* Add link to package.xml

* Add links to controller docs on control.ros.org

* Set check-yaml syntax instead of ignoring

(cherry picked from commit 731da8e)

.github/workflows/rosdoc2.yml

@@ -0,0 +1,14 @@
+name: rosdoc2
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - ros2_controllers/doc/**
+      - ros2_controllers/rosdoc2.yaml
+      - ros2_controllers/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
+        args: ["--allow-multiple-documents"]
       - id: debug-statements
       - id: end-of-file-fixer
       - id: mixed-line-ending
@@ -104,6 +105,7 @@ repos:
         description: Check if copyright notice is available in all files.
         entry: ament_copyright
         language: system
+        exclude: .*/conf\.py$
 
   # Docs - RestructuredText hooks
   - repo: https://github.com/PyCQA/doc8

ros2_controllers/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"

ros2_controllers/doc/index.rst

@@ -0,0 +1,80 @@
+Welcome to the documentation for ros2_controllers
+=================================================
+
+For more information of the ros2_control framework see `control.ros.org <https://control.ros.org/>`__.
+
+.. list-table::
+  :header-rows: 1
+
+  * - Package Name
+    - Documentation
+    - API
+    - ROS Index
+  * - ackermann_steering_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/ackermann_steering_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/ackermann_steering_controller/>`__
+    - `ROS Index <https://index.ros.org/p/ackermann_steering_controller/>`__
+  * - admittance_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/admittance_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/admittance_controller/>`__
+    - `ROS Index <https://index.ros.org/p/admittance_controller/>`__
+  * - bicycle_steering_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/bicycle_steering_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/bicycle_steering_controller/>`__
+    - `ROS Index <https://index.ros.org/p/bicycle_steering_controller/>`__
+  * - diff_drive_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/diff_drive_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/diff_drive_controller/>`__
+    - `ROS Index <https://index.ros.org/p/diff_drive_controller/>`__
+  * - effort_controllers
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/effort_controllers/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/effort_controllers/>`__
+    - `ROS Index <https://index.ros.org/p/effort_controllers/>`__
+  * - force_torque_sensor_broadcaster
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/force_torque_sensor_broadcaster/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/force_torque_sensor_broadcaster/>`__
+    - `ROS Index <https://index.ros.org/p/force_torque_sensor_broadcaster/>`__
+  * - forward_command_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/forward_command_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/forward_command_controller/>`__
+    - `ROS Index <https://index.ros.org/p/forward_command_controller/>`__
+  * - imu_sensor_broadcaster
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/imu_sensor_broadcaster/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/imu_sensor_broadcaster/>`__
+    - `ROS Index <https://index.ros.org/p/imu_sensor_broadcaster/>`__
+  * - joint_state_broadcaster
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/joint_state_broadcaster/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/joint_state_broadcaster/>`__
+    - `ROS Index <https://index.ros.org/p/joint_state_broadcaster/>`__
+  * - joint_trajectory_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/joint_trajectory_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/joint_trajectory_controller/>`__
+    - `ROS Index <https://index.ros.org/p/joint_trajectory_controller/>`__
+  * - pid_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/pid_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/pid_controller/>`__
+    - `ROS Index <https://index.ros.org/p/pid_controller/>`__
+  * - position_controllers
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/position_controllers/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/position_controllers/>`__
+    - `ROS Index <https://index.ros.org/p/position_controllers/>`__
+  * - range_sensor_broadcaster
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/range_sensor_broadcaster/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/range_sensor_broadcaster/>`__
+    - `ROS Index <https://index.ros.org/p/range_sensor_broadcaster/>`__
+  * - steering_controllers_library
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/steering_controllers_library/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/steering_controllers_library/>`__
+    - `ROS Index <https://index.ros.org/p/steering_controllers_library/>`__
+  * - tricycle_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/tricycle_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/tricycle_controller/>`__
+    - `ROS Index <https://index.ros.org/p/tricycle_controller/>`__
+  * - tricycle_steering_controller
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/tricycle_steering_controller/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/tricycle_steering_controller/>`__
+    - `ROS Index <https://index.ros.org/p/tricycle_steering_controller/>`__
+  * - velocity_controllers
+    - `Documentation <https://control.ros.org/master/doc/ros2_controllers/velocity_controllers/doc/userdoc.html>`__
+    - `API <http://docs.ros.org/en/rolling/p/velocity_controllers/>`__
+    - `ROS Index <https://index.ros.org/p/velocity_controllers/>`__

ros2_controllers/package.xml

@@ -8,6 +8,8 @@
 
   <license>Apache License 2.0</license>
 
+  <url type="website">https://control.ros.org</url>
+
   <buildtool_depend>ament_cmake</buildtool_depend>
 
   <exec_depend>ackermann_steering_controller</exec_depend>

ros2_controllers/rosdoc2.yaml

@@ -0,0 +1,20 @@
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings:
+    # Not generating any documentation of code
+    generate_package_index: false
+    always_run_doxygen: false
+    enable_breathe: false
+    enable_exhale: false
+    always_run_sphinx_apidoc: false
+
+builders:
+   # Configure Sphinx with the location of the docs:
+    - sphinx: {
+        name: 'ros2_controllers',
+        sphinx_sourcedir: 'doc',
+        output_dir: ''
+      }