Choice of breathe/exhale over Doxygen

[rkent]

I've looked at a few of the larger projects, that took the time to properly use Doxygen to document their projects. What I am seeing is that, at the individual class level, the breathe/exhale output looks good if not better than the Doxygen html output.

But at higher levels, breathe/exhale makes it hard to find the class you are looking for.

Here is an example:

nav2_behavior_tree class list

• in breathe/exhale: https://docs.ros.org/en/iron/p/nav2_behavior_tree/generated/index.html#full-c-api
• in doxygen: https://docs.ros.org/en/iron/p/nav2_behavior_tree/generated/doxygen/html/annotated.html

The difference is that nav2_behavior_tree includes the "@brief" tag in C++ documentation. Doxygen provides a nice list of classes with their "@brief" description. breathe/exhale does not show that description, plus the list is much more liberal in use of space, so there is a lot of scrolling to see all of the classes.

If I was trying to use this API and find the right class, the Doxygen output is much easier to use.

I don't really have an answer for this. In the latest rkent/rosdoc2 versions, I included an option to show the Doxygen html instead of, or in addition to, the breathe/exhale one. But it does not really integrate well, as it takes you away from the overall page so you lose the TOC links. But if I was the author of a package that had worked hard to document C++ according to Doxygen standards, I would prefer my users saw that instead of breathe/exhale.

On the other hand, nav2 has its own documentation at https://docs.nav2.org/behavior_trees/index.html. Another option in rkent/rosdoc2 is to specify a URL to use in place of out "Documentation" link, and they would probably just replace that.

But in any case, I typically find the C++ documentation very hard to navigate in breathe/exhale.

[clalancette]

But it does not really integrate well, as it takes you away from the overall page so you lose the TOC links.

This was the main reason we chose breathe/exhale; just generating the Doxygen site does not integrate into the rest of the generated documentation.

Overall, I agree that using breathe/exhale isn't great; besides it not formatting that nicely, we've also had problems with it being able to properly parse all of the C++ that we use.

All of that said, my view here has always been that the solution is to improve breathe and exhale. Communities around both of those projects are somewhat active, and a couple of us have write access to exhale. So this should be doable.

[rkent]

Having breathe/exhale crash, and therefore prevent rosdoc2 from showing anything at all, was the original motivation that got me to add the feature to optionally show Doxygen. At first, I just disabled breathe/exhale to stop the crash in a particular package. But some packages looked really good in Doxygen, it was a pity not to show them. So I added a feature to enable showing the Doxygen as well.

Here is an example.ecl_containers. It does not show at all in https://docs.ros.org/en/rolling/p/ presumably because it was crashing. In my test version, you can see how it looks at http://rosdoc2.rosdabbler.com/ecl_containers/. That repo does not seem to have externally hosted documentation, but has really nice Doxygen annotation of their C++. See http://rosdoc2.rosdabbler.com/ecl_containers/generated/doxygen/html/annotated.html

[tfoote]

Here's more about the early design choices: https://design.ros2.org/articles/per_package_documentation.html