You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
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.
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
The text was updated successfully, but these errors were encountered:
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.
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.
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
: inapi/[c-cpp-identifier].rst
.breathe
: through the.. doxygenindex::
directive in theindex.rst
file.Fix
There are a few ways to approach this problem:
:doxygenindex:
directive from the package'sindex.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.breathe-apidoc
utility instead of theexhale
extension to generate restructured text files from the doxygen XML output. This is listed as a "less-involved" alternative forexhale
on its documentation. The downside is that class/file hierarchies may not be as well-represented - which is somethingexhale
excels at.breathe-apidoc
would also involve significant changes to theSphinxBuilder
class since it involves programmatic invocation, rather than just listingbreathe
as an extension tosphinx
.:doxygenindex:
directive in the package'sindex.rst
file regardless, and either ignore the warnings or figure out a way to suppress the warnings - this is unlikely, sincesphinx
'ssuppress_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 byexhale
.For visual reference: I've attached two screenshots, one of the index page with the
:doxygenindex:
directive, and one without.With directive
Without directive
The text was updated successfully, but these errors were encountered: