Checklist for supporting document generation for ament_python packages

Automatic document generation for python (ament_python) packages in the ROS ecosystem has been a long pending ask and the purpose of this ticket is to serve as a checklist of PRs/patches to land to deliver this functionality.

PRs/Code to merge into this repo in specific order:

[x] https://github.com/ros-infrastructure/rosdoc2/pull/28: Bulk of the required code is in this feature branch
[x] https://github.com/rkent/rosdoc2/commit/3fb714120e594e80f58d8fe45658f369368fd13d: Port changes to sphinx_builder.py to append pkg source directory to system path when using autogenerated conf.py.
[x] https://github.com/ros-infrastructure/rosdoc2/pull/47
[x] TODO: Similar to #47, also copy package_src_directory made available from https://github.com/rkent/rosdoc2/commit/3fb714120e594e80f58d8fe45658f369368fd13d into docs_build such that the python interpreter can access pakg modules when running the user written conf.py file
[x] https://github.com/Yadunund/rosdoc2/commit/af64741619e269897b90da1a1e5a3275d0cb71b6: Correctly populate autodoc_mock_imports with python modules that are listed as system packages in package.xml (eg. python3-babeltrace).
[x] https://github.com/Yadunund/rosdoc2/commit/226f90562be408979902d5102d68f96ced173ffc: Include <doc_depend> dependencies in list of modules to include in autodoc_mock_imports
[ ] Bonus: Update sphix_builder.py to not always overwrite any user specific autodoc_mock_imports with exec_depend modules.

I've incorporated all these changes into temporary branch for my testing and I'm pleased to share that document generation has gone well for most of the ament_python packages in the ros2 org. Along the way I've had to make some changes some packages to successfully generate documentation. Most of the changes are related to populating the package.xml with missing exec_depends. Without this, autodoc will try to import these dependency modules when importing the module to be documented. The downside of this is that cross-reference across pkgs is not yet supported but I'll discuss this and other todo's for the future later below. Other changes include fixes to docstrings to comply with sphinx/autodoc spec.

PRs to merge to generate documentation without any warnings

Document generation results using combined changes

Pkg	Works?
action_tutorials_py	✅
demo_nodes_py	✅
domain_coordinator	✅
examples_rclpy_executors	✅
examples_rclpy_guard_conditions	✅
examples_rclpy_minimal_action_client	✅
examples_rclpy_minimal_action_server	✅
examples_rclpy_minimal_client	✅
examples_rclpy_minimal_publisher	✅
examples_rclpy_minimal_service	✅
examples_rclpy_minimal_subscriber	✅
examples_rclpy_pointcloud_publisher	✅
examples_tf2_py	✅
launch	✅
launch_pytest	✅
launch_ros	❌
launch_testing	✅
launch_testing_examples	✅
launch_testing_ros	✅
launch_xml	✅
launch_yaml	✅
lifecycle_py	✅
quality_of_service_demo_py	✅
rclpy	❌
ros2action	✅
ros2bag	✅
ros2cli	✅
ros2component	✅
ros2doctor	✅
ros2interface	✅
ros2launch	✅
ros2lifecycle	✅
ros2multicast	✅
ros2node	✅
ros2param	✅
ros2pkg	✅
ros2run	✅
ros2service	✅
ros2test	✅
ros2topic	✅
ros2trace	✅
rosidl_cli	✅
rosidl_pycommon	✅
rosidl_runtime_py	✅
rpyutils	❌
sensor_msgs_py	✅
sros2	✅
test_launch_ros	✅
test_tracetools_launch	✅
tf2_ros_py	✅
tf2_tools	✅
topic_monitor	✅
tracetools_launch	✅
tracetools_read	✅
tracetools_test	✅
tracetools_trace	✅

ros-infrastructure / rosdoc2