Fix errors in documentation generation.

[rkent]

I'm currently going through this repository, fixing errors in rosdoc2 documentation generation, starting with the tf2 package.

But I have a question (if anyone is listening!).

The conf.py in tf2 has a lot of extra, unneeded stuff, and I would like to remove the cruft. The stuff added for rosdoc2 I understand. But my question is this:

Is there any need to support other other modes of documentation generation, beyond rosdoc2? For example, there is code there that is only useful for one or more of the following documentation generations: htmlhelp, latex, man_pages, texinfo, or epub. None of these are needed for rosdoc2 generation.

The changes that are needed go beyond fixing the cruft in conf.py. For example, Vector3 is not documented due to a configuration error that I can fix. But the immediate question concerns the non-rosdoc2 cruft.

[rkent]

In a branch I am working on, I have fixed a few issues that were occurring and showing warnings on documentation generation. I think I'll use this issue to comment on a few other issues.

file-level \author tags.

Many files have a line:
/** \author Tully Foote */
after the license boilerplate, but before a namespace declaration. This was intended to be a file-level comment, but both Doxygen and Breathe/Exhale call it a namespace comment. I can move it to a file-level comment, but then there's a new issue: Doxygen recognizes it as an Author, but Breathe/Exhale does not seem to recognize \author so it just shows up as "Detailed Description" I believe this is an Exhale bug.

Whether this \author is assigned to the file or the namespace, in the Breathe/Exhale output it appears as:

Detailed Description

  Tully Foote

while the Doxygen output properly inserts Author: Tully Foote

I believe I'll change this to:

/** \file
    Author: Tully Foote
*/

which looks fine on both Doxygen as well as Breathe/Exhale, with the downside of loss of xml metadata that we are not using anyway.

Exhale does not support external namespace references

Doxygen is recognizing namespace tf2 extensions in the tf2 package that are coming from cross references, but cannot find the defining file. So the output generates warning messages like:

Did not locate file that defined function [tf2::transformToBullet]; no link generated.

The effect of this on the output is that namespace tf2 in package tf2 shows functions like tf2::transformToBullet but it does not show the full definition of the function. However, the full definition of that function does show up in the package tf2_bullet package documentation.

This is caused because exhale does not recognize function definitions that are declared using the external attribute, such as those that are coming in from cross-references. See Support linking to external docs using Doxygen tags

The current build farm does not fully support documentation cross-references, but with documentation generation for a single repository, all packages are built in a single run, so later packages receive cross-references from earlier packages. tf2 for random reasons is one of the last packages built, so it is getting cross-references from earlier packages (like tf2_bullet). That then expands the namespace tf2 definition in package tf2 but it cannot find the full function definition due to the exhale bug. Fixing this is not trivial at the exhale level, and probably not worth the effort. From a rosdoc2 perspective, it should probably not be pulling in cross-references from everything it finds, but probably only from package depends. I think I'll change that, which would change the way namespace tf2 appears in package tf2 so it does not show functions that are defined in tf2_bullet (and other packages in geometry2)

[kscottz]

Hi @rkent

We discussed this in the Waffle meeting.

Is there any need to support other other modes of documentation generation, beyond rosdoc2? For example, there is code there that is only useful for one or more of the following documentation generations: htmlhelp, latex, man_pages, texinfo, or epub. None of these are needed for rosdoc2 generation.

Short answer, no, you are more than welcome to uncruftify conf.py. Just sent over a PR.

With respect to the other changes, please send us a PR with the changes you want and we can take a look. Alternatively, if you can provide a succinct list of desired changes as an issue I can try and get someone from the community to give it a shot and you can review.

[rkent]

OK, thanks. I'll do a PR request for this.

Unfortunately it requires changes to rosdoc2 due to ros-infrastructure/rosdoc2#204 I have those changes ready, as well as the PR for geometry2, but I have 2 open PRs on rosdoc2 already, and I want those landed before I push forward with this issue.