breathe-doc / breathe

ReStructuredText and Sphinx bridge to Doxygen
https://breathe-doc.org
Other
755 stars 201 forks source link

add option to no-link all directives in apidoc #378

Open vermeeren opened 6 years ago

vermeeren commented 6 years ago

This will probably allow apidoc builds and manual directives to be mixed in the resulting sphinx build without triggering duplicate declaration warnings.

rowanG077 commented 6 years ago

This doesn't solve the warnings. no-link controls whether a permalink is added to the declaration it has nothing to do with the declaration itself. What would work is adding the no-index option to the underlying sphinx domain directive but this option is not exposed through breathe. Besides it's not clear from the sphinx documentation that this is actually the correct way to circumvent this duplicate declaration warning.

There is an open issue for this on sphinx GitHub but no-index is not mentioned so I think it's not a documented way to handle this. But until this is resolved in Sphinx itself no-index could be a solution

See: https://github.com/sphinx-doc/sphinx/issues/4981

vermeeren commented 6 years ago

What lead me to this idea was mainly the doc on the no-link option:

This allows you to have your main reference listings somewhere with targets, but then to be able to sneak in repeat directives into other parts of the documentation to illustrate particular points without Sphinx getting confused what should be linked to by other references.

Indeed I haven't looked into things or tested them out yet, I made the issue yesterday so I wouldn't forget. Thanks for the link to upstream.

Also tagging @jakobandersen so he is up-to-date.

chausner-audeering commented 3 years ago

I am running into the same issue. I am already using :no-link: to avoid link target conflicts but it would also be nice to get rid of the "WARNING: Duplicate C++ declaration" warning. The :no-index: workaround that @rowanG077 mentioned does not seem to be applicable without modifying Breathe, right?

jakobandersen commented 3 years ago

See also https://github.com/michaeljones/breathe/issues/594#issuecomment-733820197: the :no-link: option may do something on the Breathe side (I forgot), but on the Sphinx side it has been broken for a long time, and has now been removed (for the C and C++ domains). How to resolve the problem depends a lot on what you are trying to achieve in your documentation. Sometimes the alias directives may be a solution, e.g., if you would like a synopsis-like construct. Sometimes some extra namespacing does it, e.g., as in the Breathe docs where you would like to show the same example multiple times with slight variations.