Add pydoclint (#186)

Jelmerdw · Max Waterhout · web-flow · commit af3a133d35e3 · 2025-05-28T10:15:00.000+02:00
* Add ruff checks to  the pyproject.toml

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Add docstrings to rcdt_actions

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* add docstrings to rcdt_franka

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added docstrings to pyflow package

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added docstrings to rcdt_gazebo

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* added docstring to moveit

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* added docstring to rcdt_sensors

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added docstrings to rcdt_joystick

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added docstrings to rcdt_mobile_manipulator

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* added docstrings to rcdt_panther

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added docstrings to rcdt_utilities

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added docstring to rcdt_detection

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Update ruff configuration to include DOC in select and remove exclusion for rcdt_detection

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Added preview mode and extra ruff functions to the pyproject.toml

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Add norecursedirs option to pytest configuration

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Ruff format

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Ruff and Ty fixes

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;

* Use Any as type.

Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;

* Add pydoclint to docker.

Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;

* Install flake8 bin via apt.

Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;

* Add pydoclint to workflow.

Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;

* Undo ignore of ruff rule.

Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;

* Add documentation.

Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;

---------

Signed-off-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;
Signed-off-by: Jelmer de Wolde &lt;jelmer.de.wolde@alliander.com&gt;
Co-authored-by: Max Waterhout &lt;max.waterhout@soprasteria.com&gt;
diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml
@@ -21,6 +21,16 @@ jobs:
       - run: ruff format --check
       - run: ruff check
 
+  pydoclint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - run: pip install pydoclint
+      - run: pydoclint ros2_ws/src
+
   clang-format:
     runs-on: ubuntu-latest
     steps:
diff --git a/dockerfiles/install_scripts/dev_packages.sh b/dockerfiles/install_scripts/dev_packages.sh
@@ -11,6 +11,8 @@ pip install pytest-timeout
 pip install ruff
 pip install ty
 pip install termcolor
+pip install pydoclint[flake8]
+pip install Flake8-pyproject
 
 # Specifying numpy range to work with ROS and Ultralytics:
 pip install "numpy>=1.23.0,<2.0"
@@ -20,6 +22,7 @@ pip install "transforms3d>=0.4.2"
 
 sudo apt update
 sudo apt install -y \
+    flake8 \
     ros-humble-navigation2 \
     ros-humble-nav2-bringup \
     ros-humble-slam-toolbox 
diff --git a/docs/content/workflows.md b/docs/content/workflows.md
@@ -10,11 +10,14 @@ We make use of different Github workflows to automatically validate the code in
 
 ## Linting
 
-The Linting workflow contains three checks:
+The Linting workflow contains the following checks:
 
 - **ruff**:\
 Checks the format and style of the .py files in this repository, using the rules specified in *pyproject.toml*.
 
+-**pydoclint**\:
+Checks the docstring of the .py files in the rosw_ws/src directory, using the rules specified in *pyproject.toml*. These checks might be implemented in Ruff in the [future](https://github.com/astral-sh/ruff/issues/12434), but for now we use pydoclint for the additional checks not available in Ruff.
+
 - **clang-format**:\
 Checks the format of the .cpp, .h and .hpp files in this repository.
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -31,3 +31,17 @@ extra-paths = [
     "ros2_ws/src/rcdt_utilities/",
     "ros2_ws/src/rcdt_gazebo/",
 ]
+
+# Settings of pydoclint, also in flake8 to use in vscode:
+[tool.flake8]
+style = "google"
+skip-checking-short-docstrings = false
+allow-init-docstring = true
+check-style-mismatch = true
+select = "DOC"
+
+[tool.pydoclint]
+style = "google"
+skip-checking-short-docstrings = false
+allow-init-docstring = true
+check-style-mismatch = true
diff --git a/ros2_ws/src/rcdt_actions/rcdt_actions/definitions/definitions.py b/ros2_ws/src/rcdt_actions/rcdt_actions/definitions/definitions.py
@@ -190,9 +190,9 @@ class Sequence:
     actions: list[Action]
     node: Node | None = None
     goal_handle: ServerGoalHandle | None = None
-    last_result = None
-    success = True
-    index = 0
+    last_result: object = None
+    success: bool = True
+    index: int = 0
 
     def reset(self) -> None:
         """Reset the sequence to its initial state."""
diff --git a/ros2_ws/src/rcdt_actions/src_py/action_executor.py b/ros2_ws/src/rcdt_actions/src_py/action_executor.py
@@ -72,8 +72,12 @@ def callback(self, goal_handle: ServerGoalHandle) -> Sequence.Result:
         return result
 
 
-def main(args: str = None) -> None:
-    """Main function to initialize the ROS 2 node and start the action executor."""
+def main(args: str | None = None) -> None:
+    """Main function to initialize the ROS 2 node and start the action executor.
+
+    Args:
+        args (str | None): Command line arguments. Defaults to None.
+    """
     rclpy.init(args=args)
     executor = MultiThreadedExecutor()
     node = ActionExecutor()
diff --git a/ros2_ws/src/rcdt_detection/rcdt_detection/mask_properties.py b/ros2_ws/src/rcdt_detection/rcdt_detection/mask_properties.py
@@ -18,7 +18,6 @@
     Quaternion,
 )
 from rclpy import logging
-from typing_extensions import Self
 
 from rcdt_detection.image_manipulation import three_to_single_channel
 
@@ -237,7 +236,7 @@ def mode_depth(self) -> float:
         masked_depth_values = self.depth_image[self.single_channel > 0]
         return np.bincount(masked_depth_values).argmax()
 
-    def refined_mask(self) -> Self:
+    def refined_mask(self) -> "MaskProperties":
         """Returns a refined mask based on the mode depth value.
 
         The refined mask is created by applying a condition that keeps only the pixels within a certain range around the mode depth value.
diff --git a/ros2_ws/src/rcdt_detection/src_py/get_mask_properties.py b/ros2_ws/src/rcdt_detection/src_py/get_mask_properties.py
@@ -21,10 +21,6 @@ class GetMaskProperties(Node):
 
     This node provides a service that takes a mask, depth image, and camera info,
     and returns properties such as contour, bounding box, centroid, and average hue.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/get_rgbd_from_topic.py b/ros2_ws/src/rcdt_detection/src_py/get_rgbd_from_topic.py
@@ -19,10 +19,6 @@ class GetRGBDFromTopic(Node):
 
     This node provides a service that waits for an RGBD message on a specified topic
     and returns the RGB image, depth image, and their respective camera info.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/pose_from_pixel.py b/ros2_ws/src/rcdt_detection/src_py/pose_from_pixel.py
@@ -21,10 +21,6 @@ class PoseFromPixel(Node):
 
     This node provides a service that takes a pixel location and depth image,
     and returns the 3D pose of that pixel in the camera's coordinate frame.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/publish_image.py b/ros2_ws/src/rcdt_detection/src_py/publish_image.py
@@ -19,10 +19,6 @@ class PublishImage(Node):
 
     This node provides a service that takes an image and a topic name,
     and publishes the image to that topic.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/publish_masks.py b/ros2_ws/src/rcdt_detection/src_py/publish_masks.py
@@ -22,10 +22,6 @@ class PublishMasks(Node):
     This node provides a service that takes a list of masks and a topic name,
     combines the masks by taking the maximum value across all masks, and publishes
     the combined mask to the specified topic.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/segment_image.py b/ros2_ws/src/rcdt_detection/src_py/segment_image.py
@@ -25,10 +25,6 @@ class SegmentImage(Node):
 
     This node provides a service that takes an input image, applies segmentation,
     and returns the segmented image along with individual masks for each segment.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/select_image_from_list.py b/ros2_ws/src/rcdt_detection/src_py/select_image_from_list.py
@@ -18,10 +18,6 @@ class SelectImageFromList(Node):
 
     This node provides a service that allows the selection of an image from a list
     based on an index provided in the request.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/select_pick_location.py b/ros2_ws/src/rcdt_detection/src_py/select_pick_location.py
@@ -27,10 +27,6 @@ class SelectPickLocation(Node):
     This node provides a service that processes masks and depth images to determine
     the best pick location. It uses the MaskProperties class to analyze each mask
     and returns the most suitable pick location based on the refined mask properties.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_detection/src_py/select_place_location.py b/ros2_ws/src/rcdt_detection/src_py/select_place_location.py
@@ -23,10 +23,6 @@ class SelectPlaceLocation(Node):
     pattern. It starts from a base layer and moves upwards, adjusting the x and y
     coordinates based on the current layer and row index. The pose is returned in a
     ROS-compatible format.
-
-    Attributes:
-        node_name (str): The name of the node.
-        service_name (str): The name of the service provided by this node.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_gazebo/launch/gazebo_robot.launch.py b/ros2_ws/src/rcdt_gazebo/launch/gazebo_robot.launch.py
@@ -4,7 +4,6 @@
 
 
 import xml.etree.ElementTree as ET
-from typing import List
 
 from launch import LaunchContext, LaunchDescription
 from launch.actions import ExecuteProcess, OpaqueFunction
@@ -21,7 +20,7 @@
 use_velodyne_arg = LaunchArgument("velodyne", False, [True, False])
 
 
-def launch_setup(context: LaunchContext) -> List:
+def launch_setup(context: LaunchContext) -> list:
     """Setup the launch description for the Gazebo simulation with robots.
 
     Args:
@@ -31,7 +30,7 @@ def launch_setup(context: LaunchContext) -> List:
         ValueError: If the SDF file does not contain a world attribute with a name.
 
     Returns:
-        List: A list of actions to be executed in the launch description.
+        list: A list of actions to be executed in the launch description.
     """
     load_gazebo_ui = load_gazebo_ui_arg.bool_value(context)
     world = world_arg.string_value(context)
diff --git a/ros2_ws/src/rcdt_joystick/src_py/joy_to_gripper.py b/ros2_ws/src/rcdt_joystick/src_py/joy_to_gripper.py
@@ -21,14 +21,6 @@ class JoyToGripper(Node):
 
     This node subscribes to joystick input and calls the appropriate service
     to open or close the gripper based on button presses.
-
-    Attributes:
-        open_gripper (Client): Client for the open gripper service.
-        close_gripper (Client): Client for the close gripper service.
-        mapping (dict): Mapping of joystick buttons to gripper actions.
-        button_actions (dict): Dictionary mapping button indices to actions.
-        button_states (dict): Dictionary to track the state of each button.
-        busy (bool): Flag to indicate if the node is currently processing a request.
     """
 
     def __init__(self):
diff --git a/ros2_ws/src/rcdt_joystick/src_py/joy_to_twist.py b/ros2_ws/src/rcdt_joystick/src_py/joy_to_twist.py
@@ -18,12 +18,6 @@ class JoyToTwist(Node):
     """A ROS2 node that converts joystick input to Twist messages.
 
     This node subscribes to joystick input and publishes Twist messages based on the joystick axes and buttons.
-
-    Attributes:
-        pub (Publisher): Publisher for the Twist or TwistStamped messages.
-        mapping (dict): Mapping of joystick axes to Twist message fields.
-        twist_msg (Twist): The Twist message to be published.
-        twist_stamped_msg (TwistStamped): The TwistStamped message to be published if stamped is True.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_joystick/src_py/joy_topic_manager.py b/ros2_ws/src/rcdt_joystick/src_py/joy_topic_manager.py
@@ -59,12 +59,6 @@ class JoyTopicManager(Node):
     This node subscribes to a joystick input topic and publishes Joy messages to specific topics
     based on the configuration defined in a YAML file. It allows dynamic topic switching
     based on joystick button states.
-
-    Attributes:
-        outputs (list[Output]): List of Output configurations loaded from the YAML file.
-        pubs (dict[str, Publisher]): Dictionary mapping topic names to their corresponding publishers.
-        topic (str | None): The currently active topic to which Joy messages are being published.
-        state_pub (Publisher): Publisher for the current state of the active topic.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_panther/rcdt_panther/test/end_to_end/test_panther.py b/ros2_ws/src/rcdt_panther/rcdt_panther/test/end_to_end/test_panther.py
@@ -17,7 +17,7 @@ def panther_launch() -> LaunchDescription:
     """Fixture to create launch file for panther robot.
 
     Returns:
-        RegisteredLaunchDescription: The launch description for the panther robot.
+        LaunchDescription: The launch description for the panther robot.
     """
     panther = RegisteredLaunchDescription(
         get_file_path("rcdt_panther", ["launch"], "panther.launch.py"),
diff --git a/ros2_ws/src/rcdt_sensors/src_py/combine_camera_topics.py b/ros2_ws/src/rcdt_sensors/src_py/combine_camera_topics.py
@@ -20,10 +20,6 @@ class CombineCameraTopics(Node):
     This node subscribes to the RGB and depth image topics, as well as their corresponding
     camera info topics. It publishes a combined RGBD message that contains both the RGB image
     and the depth image, along with their camera information.
-
-    Attributes:
-        rgbd (RGBD): The combined RGBD message containing RGB and depth images.
-        pub (Publisher): Publisher for the RGBD message.
     """
 
     def __init__(self) -> None:
@@ -55,19 +51,35 @@ def publish_rgbd(self) -> None:
         self.pub.publish(self.rgbd)
 
     def update_rgb(self, msg: Image) -> None:
-        """Update the RGB image in the RGBD message."""
+        """Update the RGB image in the RGBD message.
+
+        Args:
+            msg (Image): The incoming RGB image message.
+        """
         self.rgbd.rgb = msg
 
     def update_depth(self, msg: Image) -> None:
-        """Update the depth image in the RGBD message."""
+        """Update the depth image in the RGBD message.
+
+        Args:
+            msg (Image): The incoming depth image message.
+        """
         self.rgbd.depth = msg
 
     def update_rgb_info(self, msg: CameraInfo) -> None:
-        """Update the RGB camera info in the RGBD message."""
+        """Update the RGB camera info in the RGBD message.
+
+        Args:
+            msg (CameraInfo): The incoming RGB camera info message.
+        """
         self.rgbd.rgb_camera_info = msg
 
     def update_depth_info(self, msg: CameraInfo) -> None:
-        """Update the depth camera info in the RGBD message."""
+        """Update the depth camera info in the RGBD message.
+
+        Args:
+            msg (CameraInfo): The incoming depth camera info message.
+        """
         self.rgbd.depth_camera_info = msg
 
 
diff --git a/ros2_ws/src/rcdt_sensors/src_py/convert_32FC1_to_16UC1.py b/ros2_ws/src/rcdt_sensors/src_py/convert_32FC1_to_16UC1.py
@@ -20,9 +20,6 @@ class Convert32FC1to16UC1(Node):
 
     This node subscribes to a 32FC1 depth image topic, converts the image data to
     16UC1 format (millimeters), and publishes the converted image to a new topic.
-
-    Attributes:
-        publisher (Publisher): Publisher for the converted 16UC1 depth image.
     """
 
     def __init__(self) -> None:
diff --git a/ros2_ws/src/rcdt_utilities/rcdt_utilities/launch_utils.py b/ros2_ws/src/rcdt_utilities/rcdt_utilities/launch_utils.py
diff --git a/ros2_ws/src/rcdt_utilities/rcdt_utilities/register.py b/ros2_ws/src/rcdt_utilities/rcdt_utilities/register.py
diff --git a/ros2_ws/src/rcdt_utilities/rcdt_utilities/test_utils.py b/ros2_ws/src/rcdt_utilities/rcdt_utilities/test_utils.py
