Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Let sphinx add parameter description with nested structures to documentation #652

Merged
Prev Previous commit
Next Next commit
Update parameter descriptions and include test yamls where exists
christophfroehlich committed Jan 9, 2024
commit 7aa7b3ce2fad0e2e5c94525950c476da88e98ea5
8 changes: 5 additions & 3 deletions admittance_controller/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -17,12 +17,14 @@ ROS 2 interface of the controller
Parameters
^^^^^^^^^^^

The admittance controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.

An example parameter file can be found in the `test folder of the controller <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/admittance_controller/test/test_params.yaml>`_
The admittance controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/admittance_controller/src/admittance_controller_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.

.. generate_parameter_library_details:: ../src/admittance_controller_parameters.yaml

An example parameter file for this controller can be found in `the test folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/admittance_controller/test/test_params.yaml>`_:

.. literalinclude:: ../test/test_params.yaml
:language: yaml

Topics
^^^^^^^
9 changes: 9 additions & 0 deletions diff_drive_controller/doc/parameters_context.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
linear.x: |
Joint limits structure for the linear ``x``-axis.
The limiter ignores position limits.
For details see ``joint_limits`` package from ros2_control repository.

angular.z: |
Joint limits structure for the rotation about ``z``-axis.
The limiter ignores position limits.
For details see ``joint_limits`` package from ros2_control repository.
26 changes: 5 additions & 21 deletions diff_drive_controller/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -64,28 +64,12 @@ Publishers
Parameters
,,,,,,,,,,,,

This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/diff_drive_controller/src/diff_drive_controller_parameter.yaml>`_ contains descriptions for all the parameters used by the controller.

List of parameters
=========================
.. generate_parameter_library_details:: ../src/diff_drive_controller_parameter.yaml
parameters_context.yaml

An example parameter file for this controller can be found in `the test directory <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/diff_drive_controller/test/config/test_diff_drive_controller.yaml>`_:

Note that the documentation on parameters for joint limits can be found in `their header file <https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/joint_limits/include/joint_limits/joint_limits_rosparam.hpp#L56-L75>`_.
Those parameters are:

linear.x [JointLimits structure]
Joint limits structure for the linear X-axis.
The limiter ignores position limits.
For details see ``joint_limits`` package from ros2_control repository.

angular.z [JointLimits structure]
Joint limits structure for the rotation about Z-axis.
The limiter ignores position limits.
For details see ``joint_limits`` package from ros2_control repository.

An example parameter file
=========================

.. generate_parameter_library_default::
../src/diff_drive_controller_parameter.yaml
.. literalinclude:: ../test/config/test_diff_drive_controller.yaml
:language: yaml
12 changes: 12 additions & 0 deletions force_torque_sensor_broadcaster/doc/parameters_context.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
interface_names: |
(optional) Defines custom, per axis interface names.
This is used if different prefixes, i.e., sensor name, or non-standard interface names are used.
It is sufficient that only one ``interface_name`` is defined.
This enables broadcaster use for force sensing cells with less then six measuring axes.
Example definition is:
christophfroehlich marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: yaml

interface_names:
force:
x: example_name/example_interface
21 changes: 7 additions & 14 deletions force_torque_sensor_broadcaster/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -12,24 +12,17 @@ The controller is a wrapper around ``ForceTorqueSensor`` semantic component (see

Parameters
^^^^^^^^^^^
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/force_torque_sensor_broadcaster/src/force_torque_sensor_broadcaster_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.

The interfaces can be defined in two ways, using ``sensor_name`` or ``interface_names`` parameter:
Those two parameters cannot be defined at the same time.

interface_names.[force|torque].[x|y|z] (optional)
Defines custom, per axis interface names.
This is used if different prefixes, i.e., sensor name, or non-standard interface names are used.
It is sufficient that only one ``interface_name`` is defined.
This enables broadcaster use for force sensing cells with less then six measuring axes.
Example definition is:

.. code-block:: yaml

interface_names:
force:
x: example_name/example_interface

Full list of parameters:

.. generate_parameter_library_details:: ../src/force_torque_sensor_broadcaster_parameters.yaml
parameters_context.yaml

An example parameter file for this controller can be found in `the test directory <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/force_torque_sensor_broadcaster/test/force_torque_sensor_broadcaster_params.yaml>`_:

.. literalinclude:: ../test/force_torque_sensor_broadcaster_params.yaml
:language: yaml
7 changes: 5 additions & 2 deletions gripper_controllers/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -5,11 +5,14 @@
Gripper Action Controller
--------------------------------

Controller for executing a gripper command action for simple single-dof grippers.
Controllers for executing a gripper command action for simple single-dof grippers:

- ``position_controllers/GripperActionController``
- ``effort_controllers/GripperActionController``

Parameters
^^^^^^^^^^^
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
These controllers use the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/gripper_controllers/src/gripper_action_controller_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.

List of parameters
=========================
8 changes: 5 additions & 3 deletions imu_sensor_broadcaster/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@ The controller is a wrapper around ``IMUSensor`` semantic component (see ``contr

Parameters
^^^^^^^^^^^
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/imu_sensor_broadcaster/src/imu_sensor_broadcaster_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.

List of parameters
=========================
@@ -21,5 +21,7 @@ List of parameters
An example parameter file
=========================

.. generate_parameter_library_default::
../src/imu_sensor_broadcaster_parameters.yaml
An example parameter file for this controller can be found in `the test directory <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/imu_sensor_broadcaster/test/imu_sensor_broadcaster_params.yaml>`_:

.. literalinclude:: ../test/imu_sensor_broadcaster_params.yaml
:language: yaml
7 changes: 4 additions & 3 deletions joint_state_broadcaster/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -22,18 +22,19 @@ If none of the requested interface are not defined, the controller returns error

Parameters
----------
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/joint_state_broadcaster/src/joint_state_broadcaster_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.


List of parameters
=========================
,,,,,,,,,,,,,,,,,,

.. generate_parameter_library_details::
../src/joint_state_broadcaster_parameters.yaml
joint_state_broadcaster_parameter_context.yml


An example parameter file
=========================
,,,,,,,,,,,,,,,,,,,,,,,,,

.. generate_parameter_library_default::
../src/joint_state_broadcaster_parameters.yaml
3 changes: 2 additions & 1 deletion joint_trajectory_controller/doc/parameters.rst
Original file line number Diff line number Diff line change
@@ -5,7 +5,8 @@
Details about parameters
^^^^^^^^^^^^^^^^^^^^^^^^

This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
This controller uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/joint_trajectory_controller/src/joint_trajectory_controller_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.


List of parameters
=========================
8 changes: 7 additions & 1 deletion range_sensor_broadcaster/doc/userdoc.rst
Original file line number Diff line number Diff line change
@@ -11,7 +11,8 @@ The controller is a wrapper around ``RangeSensor`` semantic component (see ``con

Parameters
^^^^^^^^^^^
The Range Sensor Broadcaster uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters.
The Range Sensor Broadcaster uses the `generate_parameter_library <https://github.com/PickNikRobotics/generate_parameter_library>`_ to handle its parameters. The parameter `definition file located in the src folder <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/range_sensor_broadcaster/src/range_sensor_broadcaster_parameters.yaml>`_ contains descriptions for all the parameters used by the controller.


List of parameters
=========================
@@ -23,3 +24,8 @@ An example parameter file

.. generate_parameter_library_default::
../src/range_sensor_broadcaster_parameters.yaml

An example parameter file for this controller can be found in `the test directory <https://github.com/ros-controls/ros2_controllers/blob/{REPOS_FILE_BRANCH}/range_sensor_broadcaster/test/range_sensor_broadcaster_params.yaml>`_:

.. literalinclude:: ../test/range_sensor_broadcaster_params.yaml
:language: yaml