search

ros-infrastructure / rosdoc2

Command-line tool for generating documentation for ROS 2 packages.
Apache License 2.0
39 stars 9 forks source link

Document parameters from YAML file required by generate_parameter_library #142

Open mateusmenezes95 opened 2 months ago

mateusmenezes95 commented 2 months ago

This proposal outlines the creation of a feature to parse the .yaml file required by the generate_parameter_library (if the package uses it) and generate a page with a table or bullet points that describe the parameters necessary for the package. The generate_parameter_library sets specific requirements for the fields in the .yaml file, making it easier to translate to a .rst file with parameter descriptions, including details such as description, default_value, and values validation.

rkent commented 2 months ago

Can you point to any examples where someone has take this yaml file, and generated such a page?

Can you point to a few packages that are actually using this file?

mateusmenezes95 commented 2 months ago

Hello @rkent , I don't have an example now. I was documenting a package that I am working on and thought that this feature would be very valuable. About the packages that use the generate_parameter_library, almost all (if not all) ros2_controllers use it. Here is the file used by the diff_drive_controller.

rkent commented 2 months ago

I did a quick scan of rolling, found 'generate_parameter_library(' in CMakeLists.txt for these packages:

generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in generate_parameter_library used in

It would not be hard to located generate_parameter_library in CMakeLists.txt, extract the name and parameters, then display the raw text of the yaml file (with a little bit of text highlighting). Not saying I will do it, but is not a big job maybe a few hours of work. Don't know if the powers-that-be would support that or not.

mateusmenezes95 commented 1 month ago

Looks like they implemented this feature there. In this case it would only be up to integration