Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
aprotyas opened this issue Jul 29, 2021 · 3 comments
Closed

Comments

@aprotyas
Copy link
Contributor

aprotyas commented Jul 29, 2021

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 Fix toctree warnings and render toctree in the HTML sidebar #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

Screenshot 2021-07-29 at 14-46-13 rcpputils — rcpputils 2 2 0 documentation

Without directive

Screenshot 2021-07-29 at 14-47-44 rcpputils — rcpputils 2 2 0 documentation

@clalancette
Copy link
Contributor

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
Copy link
Contributor Author

aprotyas commented Aug 3, 2021

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
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants