ament_cmake generates no Doxygen output, but rosdoc2 still adds C++ API entry

[rkent]

Build farm output has:

03:56:44 [rosdoc2] [INFO] Skipping doxygen generation due to lack of configuration and failure to find code to automatically document.
03:56:44 [rosdoc2] [INFO] Note: the builder 'ament_cmake_export_libraries Public C/C++ API (doxygen)' did not generate any output to be copied into the destination.
03:56:44 [rosdoc2] [INFO] No doxygen_xml_directory found, apparently doxygen did not run

But later:

03:56:44 /tmp/ws/docs_build/ament_cmake_export_libraries/ament_cmake_export_libraries/wrapped_sphinx_directory/index.rst:4: WARNING: toctree contains reference to nonexisting document 'generated/index'

so rosdoc2 is trying to put a C++ API entry line when there is not DOxygen output.

This is not visible in the actual web display though.

[berndpfrommer]

In a similar situation, I have a package for which I don't want doxygen to run at all because the C++ code is not exposed as API. From the warnings I get when running rosdoc2 it seems though as if doxygen runs, even though I set always_run_doxygen to false.

[rkent]

@berndpfrommer What package is that? On many, many ROS packages, the C++ (and Python) APIs are really not useful documentation, for a variety of reasons:

• we are displaying large quantities of unexposed and often undocumented internal code, which is not useful to package users.
• the package authors have their own Doxygen setup we are not using, and our Doxygen/breathe/exhale/sphinx version does not work well
• the interesting API to users is node, message/service/action uses, and parameters, which are not easily understood from a C++ API My big-picture plan for rosdoc2, which mostly but not completely follows the original documentation proposal, is to have an overall structure that is common for all packages, with subsections like "C++ API" or "Documentation". We generate a standard default version of those with little or no effort by the package author, but allow package authors to override individual sections. So if an author knows "I don't want you to show the standard C++ API" or "I have my own version of C++ API hosted elsewhere that I would like you to expose", there is a way to do that. Unfortunately the process to get there is very slow.

[berndpfrommer]

Very well, we are in violent agreement, I have nothing to add to this. I'm working over the documentation of the flir_camera_driver repo and I'll post a link here once I have pushed the revised documentation. There are several packages that are in this repo, and there should be a README at the repo level that glues the packages together. I'm trying to get all of that working such that it looks good on github and later on rosindex. I don't think rosindex can do repo level, right? It's all package level, correct? The plan was to have, at the top of the package documentation, a link back to the repository documentation. I imagine there will be other packages which operate in the context of a group of packages. But I'm getting off thread topic here...

[rkent]

@berndpfrommer said: "I don't think rosindex can do repo level, right? It's all package level, correct?"

No, that's not correct. rosindex provides first-class support to repositories, including showing their readme. If a package readme is missing, rosindex offers the option to show the repository readme in its place.

The whole issue of package vs repository documentation is a challenging one. rosdoc2 is pretty much defined as the package-level documentation. When I tried to create a model set of packages at https://github.com/rosdabbler/fqdemo it was clear that the best way to document this was at the repository level. I resolved the issue there by putting the major documentation in the metapackage for the repository so that it would show on rosdoc2 (or my future version of it), but that is not the typical approach.

The ROS2 project needs a discussion of this fundamental issue, or if it has been discussed in the past I'd like to see the outcome.

[berndpfrommer]

The repo I'm documenting right now is here. I converted a lot of markdown to RST, and added package-level doc/conf.py files. Curious to see how the rosindex documents will look. The goal is to have good-looking documents on github and rosindex, and no broken relative links.