From 860a506219d49d60f06203c17caa8394324fcf5c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christoph=20Fr=C3=B6hlich?=
 <christophfroehlich@users.noreply.github.com>
Date: Wed, 22 May 2024 19:23:23 +0200
Subject: [PATCH] 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 731da8e43493f9da7e1be2eb8cf13154b1b240a8)
---
 .github/workflows/rosdoc2.yml  | 14 ++++++
 .pre-commit-config.yaml        |  2 +
 ros2_controllers/doc/conf.py   |  5 +++
 ros2_controllers/doc/index.rst | 80 ++++++++++++++++++++++++++++++++++
 ros2_controllers/package.xml   |  2 +
 ros2_controllers/rosdoc2.yaml  | 20 +++++++++
 6 files changed, 123 insertions(+)
 create mode 100644 .github/workflows/rosdoc2.yml
 create mode 100644 ros2_controllers/doc/conf.py
 create mode 100644 ros2_controllers/doc/index.rst
 create mode 100644 ros2_controllers/rosdoc2.yaml

diff --git a/.github/workflows/rosdoc2.yml b/.github/workflows/rosdoc2.yml
new file mode 100644
index 0000000000..0771248e79
--- /dev/null
+++ b/.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
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a34629da31..de19328805 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
+        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
diff --git a/ros2_controllers/doc/conf.py b/ros2_controllers/doc/conf.py
new file mode 100644
index 0000000000..b6134e9abd
--- /dev/null
+++ b/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"
diff --git a/ros2_controllers/doc/index.rst b/ros2_controllers/doc/index.rst
new file mode 100644
index 0000000000..f785112944
--- /dev/null
+++ b/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/>`__
diff --git a/ros2_controllers/package.xml b/ros2_controllers/package.xml
index 304088d5ab..6e8529e7e7 100644
--- a/ros2_controllers/package.xml
+++ b/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>
diff --git a/ros2_controllers/rosdoc2.yaml b/ros2_controllers/rosdoc2.yaml
new file mode 100644
index 0000000000..c5ec1b53a0
--- /dev/null
+++ b/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: ''
+      }