Support documentation generation using rosdoc2

[Yadunund]

Addresses #1080
Requires ros-infrastructure/rosdoc2#51

Here we add a custom rosdoc2.yaml file which forces rosdoc2 to generate documentation for this package as if it were an ament_python package. No underlay needs to be sourced.

Cavats:

1. If I set sphinx_sourcedir to docs/source in the rosdoc2.yaml file, ie, if we provide the custom conf.py file there several hundred warnings reported by autodoc. I noticed that these warnings go away when using the default conf.py file that rosdoc2 generates and hence left out the custom sourcedir. Perhaps this can be done for future work.

2. I had to add a few rclpy submodules as doc_depends such that autodoc will mock these modules when trying to import them. Without this, there are several type errors thrown upon import as these submodules load constants from python C modules.
   Open to any suggestions here!

Detailed errors below:

  File "home/yadunund/ws_rosdoc2/docs_build/rclpy/rclpy/duration.py", line 31, in __init__
    total_nanoseconds += int(nanoseconds)
TypeError: int() argument must be a string, a bytes-like object or a real number, not 'RMW_DURATION_INFINITE'

  File "/home/yadunund/ws_rolling/src/ros2/rclpy/rclpy/rclpy/qos.py", line 444, in <module>
    qos_profile_unknown = QoSProfile(**_rclpy.rmw_qos_profile_t.predefined(
  File "/usr/local/google/home/yadunund/ws_rolling/src/ros2/rclpy/rclpy/rclpy/qos.py", line 82, in __init__
    raise InvalidQoSProfileException('History and/or depth settings are required.')
rclpy.qos.InvalidQoSProfileException: ('Invalid QoSProfile', 'History and/or depth settings are required.')

  File "/home/yadunund/ws_rolling/src/ros2/rclpy/rclpy/rclpy/clock.py", line 126, in __new__
    if not isinstance(clock_type, ClockType):
TypeError: isinstance() arg 2 must be a type, a tuple of types, or a union

[clalancette]

CI:

• Linux
• Linux-aarch64
• Windows

[wjwwood]

Is there any discussion about this anywhere? I'd like to understand it better, because it seems... like an abuse of the dependency system.

[Yadunund]

Not apart from what was mentioned in the PR description. I agree we're taking advantage of the doc_depend tag but I couldn't find a better way to deal with the import errors. I'm all ears for a better solution!