Lately I've been examining packages that fail to generate a rosdoc2 output. By far the most common cause of this is that the package claims to be python (either as ament_python or ament_cmake_python) but rosdoc2 fails to find the python package in a standard or specified (via rosdoc2.yaml) location.
Here's some notes of mine on failing python packages, and where the python is actually located:
camera_calibration: src/camera_calibration
mavros_extras: mostly c++, no python files, but has ament_cmake_python
message_filters: src/message_filters
microstrain_inertial_rqt: launch (this seems to be a launch helper, type ament_python)
nmea_navsat_driver: src/libnmea_navsat_driver (also ./launch)
nodl_python: src/nodl
ntrip_client: src/ntrip_client
python_orocos_kdl_vendor: no actual source. package has ament_cmake_python which triggers has_python
rmf_building_map_tools: many subdirectories, all under package.xml. So technically this is ./?
rmf_building_map_assets: has no python, but is type ament_python
rmf_traffic_editor_assets: has no python, but is type ament_python
rosbags_storage_mcap: has ament_cmake_python, c++ in src/, python in ros2bag_mcap_cli
rosbag2_storage_sqlite: has ament_cmake_python, python in rosbag2_sqlite3_cli
rqt: is a meta package, but has an empty resource/ directory. Type ament_python
rqt_action: source in src/rqt_action
rqt_bag: source in src/rqtbag
... this seems to be the case for all of the rqt* packages.
system_fingerprint: source in src/system_fingerprint
teleop_twist_keyboard: source in ./ that is at same level as package.xml
urdfdom_py: source in src/urdf_parser_py (that is, slightly different name than the actual package name.
vision_msgs_rviz_plugins: ament_cmake_python, mostly c++ but has samples/ directory with python.
webots_ros2_tiago: mostl resources, ament_python, but has python in launch/ directory.
Because rosdoc2 now includes documentation beyond just the code API, I don't think a complete failure is the right response to a failure to find python when expected. Also, many of these packages are using python src layout rather than flat. I think we should automatically search for python in that location as well as the standard location.
As for those that follow neither convention, it would be possible to search for python, but right now I'm thinking the right response is to just generate a warning, and proceed without generating a python API. The package author has the option of specifying the python source location using rosdoc2.yaml if they want.
Lately I've been examining packages that fail to generate a rosdoc2 output. By far the most common cause of this is that the package claims to be python (either as ament_python or ament_cmake_python) but rosdoc2 fails to find the python package in a standard or specified (via rosdoc2.yaml) location.
Here's some notes of mine on failing python packages, and where the python is actually located:
camera_calibration: src/camera_calibration mavros_extras: mostly c++, no python files, but has ament_cmake_python message_filters: src/message_filters microstrain_inertial_rqt: launch (this seems to be a launch helper, type ament_python) nmea_navsat_driver: src/libnmea_navsat_driver (also ./launch) nodl_python: src/nodl ntrip_client: src/ntrip_client python_orocos_kdl_vendor: no actual source. package has ament_cmake_python which triggers has_python rmf_building_map_tools: many subdirectories, all under package.xml. So technically this is ./? rmf_building_map_assets: has no python, but is type ament_python rmf_traffic_editor_assets: has no python, but is type ament_python rosbags_storage_mcap: has ament_cmake_python, c++ in src/, python in ros2bag_mcap_cli rosbag2_storage_sqlite: has ament_cmake_python, python in rosbag2_sqlite3_cli rqt: is a meta package, but has an empty resource/ directory. Type ament_python rqt_action: source in src/rqt_action rqt_bag: source in src/rqtbag ... this seems to be the case for all of the rqt* packages. system_fingerprint: source in src/system_fingerprint teleop_twist_keyboard: source in ./ that is at same level as package.xml urdfdom_py: source in src/urdf_parser_py (that is, slightly different name than the actual package name. vision_msgs_rviz_plugins: ament_cmake_python, mostly c++ but has samples/ directory with python. webots_ros2_tiago: mostl resources, ament_python, but has python in launch/ directory.
Because rosdoc2 now includes documentation beyond just the code API, I don't think a complete failure is the right response to a failure to find python when expected. Also, many of these packages are using python src layout rather than flat. I think we should automatically search for python in that location as well as the standard location.
As for those that follow neither convention, it would be possible to search for python, but right now I'm thinking the right response is to just generate a warning, and proceed without generating a python API. The package author has the option of specifying the python source location using rosdoc2.yaml if they want.