Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation in packages (backport #856)

[mergify]

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

Description

This PR modifies Doxygen generation in all packages that define (or extend) the tf namespace by disabling rosdoc2's default import of TAGFILES that it sees. It also modernizes any existing rosdoc2.yaml files to clearly show what has changed from default.

The existence and content of TAGFILES have a significant effect on the documentation generated by rosdoc2. See here for more details.

Within geometry2, here are some examples of the consequences of this:

• In the documentation for tf2, many functions are included that are actually defined in other packages, but without full documentation. See for example Function tf2::eigenToTransform(const Eigen::Affine3d&) which is documented (incompletely) in tf2 here Note the missing details.
• In the documentation for some namespace extension packages such as tf2_eigen, the namespace tf2 is not documented at all. That means that the details of functions such as the above, which are included in the actual .hpp code, are not shown anywhere since they are incorrect in tf2.
• In some cases, the documentation for related packages is leaking into documentation. See for example Function tf2::toMsg(const tf2::Stamped<Eigen::Affine3d>&) in tf2_kdl, where incomplete documentation from tf2_eigen is leaking.

What you see depends on the order that packages are documented in a repository, which is currently uncontrolled. But in any case, the Doxygen-> Breathe/Exhale documentation setup that we use does not handle namespace extensions well.

What this PR does is to preclude each package's documentation from including TAGFILES that were generated by other packages. That way, the tf namespace documentation will be included in each package, with the correct content, regardless of the order of running.

There may be a downside that some cross-package links may not be available, though I could not find any examples of where cross-platform links are working in the current documentation, but not after this PR.

This PR partially addresses #833.

Is this user-facing behavior change?

No, only in documentation

Did you use Generative AI?

See the header

Additional Information

To test this, you will need a recent rosdoc2 from github. After installing rosdoc2 (in a venv), run rosdoc2 twice (to generate then use TAGFILES for all packages). This is easiest done using:

rosdoc2 scan -p <directory containing geometry2>

Without this change, on the second run some of the types of problems mentioned above will appear, though might be slightly different. With these changes, in the first run and any addition runs of rosdoc2, each package should include correct documentation of tf2 classes and functions defined in that package.

---

This is an automatic backport of pull request #856 done by [Mergify](https://mergify.com).

[mergify]

Cherry-pick of 1322e89 has failed:

On branch mergify/bp/jazzy/pr-856
Your branch is up to date with 'origin/jazzy'.

You are currently cherry-picking commit 1322e89.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	new file:   tf2/rosdoc2.yaml.ild
	modified:   tf2_bullet/package.xml
	new file:   tf2_bullet/rosdoc2.yaml
	modified:   tf2_eigen/package.xml
	new file:   tf2_eigen/rosdoc2.yaml
	modified:   tf2_eigen_kdl/package.xml
	new file:   tf2_eigen_kdl/rosdoc2.yaml
	modified:   tf2_kdl/package.xml
	deleted:    tf2_kdl/rosdoc.yaml
	new file:   tf2_kdl/rosdoc2.yaml
	modified:   tf2_ros_py/rosdoc2.yaml

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)
	deleted by us:   tf2/rosdoc2.yaml
	deleted by us:   tf2_ros/rosdoc2.yaml

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally