Warning: Duplicate C/C++ declaration, also defined at `api/[file-name].rst`

[aprotyas]

What?

Every invocation of rosdoc2 build generates warnings about duplicate C/C++ declarations for every C/C++ identifier in the doxygen XML file. This warning is produced because documentation for the same C/C++ identifiers are generated in multiple places:

• exhale: in api/[c-cpp-identifier].rst.
• breathe: through the .. doxygenindex:: directive in the index.rst file.

Fix

There are a few ways to approach this problem:

1. Remove the :doxygenindex: directive from the package's index.rst file. This is the current behavior since #20 is merged. The downside is that the index page will not have a full API listing anymore, just links to the individual pages for each item in the API.
2. Use the breathe-apidoc utility instead of the exhale extension to generate restructured text files from the doxygen XML output. This is listed as a "less-involved" alternative for exhale on its documentation. The downside is that class/file hierarchies may not be as well-represented - which is something exhale excels at. breathe-apidoc would also involve significant changes to the SphinxBuilder class since it involves programmatic invocation, rather than just listing breathe as an extension to sphinx.

3. Keep the :doxygenindex: directive in the package's index.rst file regardless, and either ignore the warnings or figure out a way to suppress the warnings - this is unlikely, since sphinx's suppress_warning flag does not seem to support this type of warnings. IMHO, inclusion of this directive makes the API documentation much more easily navigable, because the entire API is listed on the front page. This avoids having users redirected to the "full API" listing generated by exhale.

   For visual reference: I've attached two screenshots, one of the index page with the :doxygenindex: directive, and one without.

With directive


Without directive


[clalancette]

Personally, I like the current behavior the best, where we don't have the full listing on the front page. For small packages, the full listing on the front page is nice, but when you get to large packages with a lot of APIs, it just becomes unwieldy. I'd rather just consistently have the front page be links.

Though I'd be interested in opinions from others.

[aprotyas]

Yes, after building the API documentation for rclcpp, I concur with your assessment about the front page. The current behavior is consistent across packages too, which is a plus.

[clalancette]

After discussion, we all decided that the current behavior is best (especially for large packages). Closing this ticket.