Documentation on Python API?

[lexi-brt]

Description

I'd like to be able to find info about using rosbag2 with python more easily. It's unclear to me at the moment if this package includes a python library to read messages out of a bag and into python objects. It would be helpful to have a README added to the repo somewhere on the python API. Examples of usage, and a list of features and functions in the python api.

Completion Criteria

• Some kind of doc page created (readme, or webpage)
• Example usage in the docs or linked from the docs
• List of functions and features in API included in the docs

Testing Notes / Suggestions

• Tests that verify that the python api usage examples work

[emersonknapp]

This is a very valid request, and it's really even bigger than this haha.

There is at least some auto-generated documentation for the C++ API via http://docs.ros.org/en/humble/p/rosbag2_cpp/ (and likewise for rosbag2_transport etc) - but it's got no structure, it's just the result of scraping docstrings. We definitely need something more cohesive.

But you're right, there's nothing at all for rosbag2_py - it's unclear to me why http://docs.ros.org/en/humble/p/rosbag2_py is a 404...

I think a very good first step on this would be to push forward #887 - then at least there would be some usage samples in the main repo. The current comment on there suggests moving it to package rosbag2_examples/rosbag2_examples_py and I agree with this. I don't think there are any major problems other than the directory structure.

[clalancette]

The reason that it is currently a 404 is that rosdoc2, our API generator, doesn't support Python. There is an open PR to add that support in ros-infrastructure/rosdoc2#28 , but we haven't found the time to finish and merge that. That's what is required to get the API documentation properly working.

[emersonknapp]

@clalancette thanks for the info - except rosbag2_py is a ament_cmake package type with C++ code, in addition to providing the python module (via CMake). I don't think I understand what criteria is being used to enable/disable the API generator?

[clalancette]

I don't think I understand what criteria is being used to enable/disable the API generator?

So if a repository has a doc entry in https://github.com/ros/rosdistro/blob/master/rolling/distribution.yaml (like rosbag2 does in https://github.com/ros/rosdistro/blob/df4f969fa591495779a9636228374279598bd848/rolling/distribution.yaml#L4477-L4480), then we will automatically attempt to run API generation on it.

That said, API generation may or may not succeed. In this case, the relevant job (for Rolling) is https://build.ros2.org/view/Rdoc/job/Rdoc__rosbag2__ubuntu_jammy_amd64/ . While the overall job is succeeding (the status is yellow), looking closer at the logs it looks like rosbag2_py is failing for some reason:

06:13:39 [rosdoc2] [INFO] No Doxyfile specified by user, no Doxyfile found in the package at '/tmp/ws/src/rosbag2/rosbag2_py/Doxyfile', and no standard include directory found at '/tmp/ws/src/rosbag2/rosbag2_py/include', therefore doxygen will not be run.
06:13:39 [rosdoc2] [INFO] Skipping doxygen generation due to lack of configuration and failure to find code to automatically document.
06:13:39 [rosdoc2] [INFO] Note: the builder 'rosbag2_py Public C/C++ API (doxygen)' did not generate any output to be copied into the destination.
06:13:39 Error the 'doxygen_xml_directory' specified '/tmp/ws/docs_build/rosbag2_py/output_staging/generated/doxygen/xml' does not exist.