breathe-doc / breathe

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

Using doxygengroup in multiple locations to summarize certain functions #893

Open 5p4k opened 1 year ago

5p4k commented 1 year ago

I have a not-so-small code base, and in the documentation I have a separate section which highlights certain functions and provides additional explanation on how to use them (let's call it "common tasks"). These functions are documented as part of their own namespace or class, while the common tasks documentation is a separate page.

In order to recall at least the function signature in common tasks page, I added the functions to a Doxygen group, and I had planned to issue the doxygengroup directive there, with the no-link option. In a minimal example:

Unique source file:

/**
 * @defgroup bars Bar functions
 */

/**
 * Some functions, some are in a group.
 */
namespace foo {
    /**
     * A type for a parameter.
     */
    struct parm {};

    /**
     * @brief Acts on the first bar.
     * @ingroup bars
     */
    void bar1(parm);

    /**
     * @brief Acts on the second bar.
     * @ingroup bars
     */
    void bar2(parm);

    /**
     * @brief Baz.
     */
    void baz();
}

Relevant RST content:

.. doxygennamespace:: foo
   :project: Test

.. doxygengroup:: bars
   :project: Test
   :no-link:

However this is not working very well:

  1. The namespace is lost: the parm type does not link to the original type.
  2. If I need to include the same group in different places on the same page (this happens in the real projects, some functions are involved in multiple common tasks), even with the no-link option, I get a WARNING: Duplicate C++ declaration

I tried using outline too but it did not help. Is there any way to work around these without having to list manually all the functions and their signature?

Ideally, what I would love to have would be

tcojean commented 3 months ago

I would like to bump this issue as I encounter a similar problem.

My use case is listing template specializations in a large project and navigating them conveniently. Currently these are not picked up by sphinx's cpp:alias command. When putting them all in a doxygengroup and having a short overview list thanks to outline, even with the no-link option, the next section does not not generate links.