Support non-default python layouts

[rkent]

Fixes #122

The changes made here are:

• a failure with the python source directory generates a warning instead of aborting
• if python source directory is not specified, then we search for it using flat layout and source layout. We prefer to find a python package with the same name as the ros package. But if not found by that name, we search for a single python package, and use that.

Tests are included for a variety of cases.

With these changes, the following packages that were not generating output before, now generate a proper output:

mavros_extras
message_filters
microstrain_inertial_rqt
nmea_navsat_driver
nodl_python
ntrip_client
python_orocos_kdl_vendor
rmf_traffic_editor_assets
rosbag2_storage_mcap
rosbag2_storage_sqlite3
rqt, plus many related packages rqt_*
system_fingerprint
webots_ros2_tiago

These packages that previously failed, now generate html but do not fully document their python:

rmf_building_map_tools: Succeeds, but has many subdirectories that are packages that it does not parse
teleop_twist_keyboard: Succeeds, but does not show python API for main file at ./ level.
urdfdom_py: Succeeds, but error in apidoc gives incomplete python API
vision_msgs_rviz_plugins: Succeeds, there is a samples/ python directory that is not parsed

One python package still fails for another reason:

camera_calibration: now has Could not import extension sphinx.ext.pngmath (exception: No module named 'sphinx.ext.pngmath'). Fails

Many of these could have been made to work previously with the correct specification in rosdoc2.yaml. But philosophically, I think we should try to succeed (with warnings) rather than just abort if the user fails to follow the conventions we expect.

[rkent]

@tfoote are you going to be able to review this?

[rkent]

Concerning "whether we should be adding complexity to support automatically discovering the non-standard layouts/naming conventions vs providing a mechanism to just set this in rosdoc2.yaml":

I feel strongly about:

• rosdoc2 should not crash (fail to generate any documentation) if the python source cannot be found.
• we should support by default both flat layout (as recommended) as well as src layout. (See the whole rqt_ universe of packages, like rqt_py_common for examples of src layout that I think we should support by default without a rosdoc2.yaml)

I don't feel strongly about fixing deviations from those two standards. One example is urdfdom_py, with the source in src/urdf_parser_py (that is, a slightly different name than the actual package name.)

But generally, I don't have a lot of confidence that package authors are going to add rosdoc2.yaml entries to fix minor differences in order to make rosdoc2 happy. I would rather have things "just work", and I am not convinced this adds much complexity to rosdoc2.

But I'll do what you want. If you want me to eliminate the search for misnamed subdirectories then I will.