Documentation fixes for tf2_kdl

[rkent]

Generated-by: Portions of this commit may include code completion from github.copilot version 1.372.0 or later

Description

This PR updates tf2_kdl so that the python API shows in rosdoc2. Issues fixed:

• rosdoc2 looks to the existence of <buildtool_depend>ament_cmake_python</buildtool_depend> in package.xml to decide to build the python API documentation. This was missing. This dependency in theory is required for ament_python_install_package in CMakeLists.txt to be found. Probably the cmake builds worked anyway since dependencies of tf2_kdl already installed ament_cmake_python, but rosdoc2 does not rely on such transitive dependencies.
• package python3-pykdl results in rosdoc2 mocking 'pykdl' but the actual python import is PyKDL. Adding this to <doc_depend> is needed to overcome this.
• the python source is in a non-standard location, hence the addition to rosdoc2.yaml.
• The documentation directory was docs/source which is a non-standard location. Documentation was moved to the supported location doc/source. Most of the stuff there was out of date, so the only thing that survived was conf.py which is identical to other conf.py in this repo. Content in mainpage.dox was moved to the README instead.

Is this user-facing behavior change?

Ideally no, it should only affect documentation.. In some forms of building, the missing buildtool_depend>ament_cmake_python</buildtool_depend> could have resulted previously in the python code not building at all, but that apparently did not actually occur. In any case I assume you wanted the python API to build, and have its documentation exposed, which is what this PR provides.

Did you use Generative AI?

See header.

[ahcorde]

Pulls: #869
Gist: https://gist.githubusercontent.com/ahcorde/b64390a6d6090667dbf1e63ff34a84c7/raw/7ab30c38617450d408c997bb34434c54b18c560c/ros2.repos
BUILD args: --packages-above-and-dependencies tf2_kdl
TEST args: --packages-above tf2_kdl
ROS Distro: rolling
Job: ci_launcher
ci_launcher ran: https://ci.ros2.org/job/ci_launcher/17741

• Linux
• Linux-aarch64
• Linux-rhel
• Windows

[ahcorde]

https://github.com/Mergifyio backport kilted jazzy humble

[mergify]

backport kilted jazzy humble

✅ Backports have been created

Details

• #872 Documentation fixes for tf2_kdl (backport #869) has been created for branch kilted but encountered conflicts
• #873 Documentation fixes for tf2_kdl (backport #869) has been created for branch jazzy but encountered conflicts
• #874 Documentation fixes for tf2_kdl (backport #869) has been created for branch humble but encountered conflicts