Fix wrong refid when SEPARATE_MEMBER_PAGES is YES

When Doxygen is configured the SEPARATE_MEMBER_PAGES set to YES, the
following Doxygen input:

```
/**
 * This struct must be used with f()
 */
struct t {
  int x;
}

/**
 * @param tx A struct t pointer
 */
void f(struct t *tx) {
  (void)tx;
}
```

The `f()` in struct t's comment generates a <ref> element with `refid`
equal to `some_prefix_compoundid_anchorid`, wheres the `id` in the
refered element ends up with an `id` equal to `some_prefix_anchorid`.
The anchorid here is the compoundid prefix by "_1", with one or two
extra 'g' prefixes for groups, so the `refid` actually has this
information duplicated.

This is a band-aid solution that, when configured enabled in conf.py,
tries to detect the issue in the refids and removes the extra baggage,
so resulting links work.

Signed-off-by: Fabio Utzig <[email protected]>

breathe/directives.py

@@ -590,6 +590,7 @@ def setup(app: Sphinx) -> None:
     app.add_config_value("breathe_doxygen_config_options", {}, True)
     app.add_config_value("breathe_use_project_refids", False, "env")
     app.add_config_value("breathe_order_parameters_first", False, 'env')
+    app.add_config_value("breathe_separate_member_pages", False, 'env')
 
     breathe_css = "breathe.css"
     if (os.path.exists(os.path.join(app.confdir, "_static", breathe_css))):

breathe/renderer/sphinxrenderer.py

@@ -431,7 +431,44 @@ def set_context(self, context: RenderContext) -> None:
         if self.context.domain == '':
             self.context.domain = self.get_domain()
 
+    # XXX: fix broken links in XML generated by Doxygen when Doxygen's
+    # SEPARATE_MEMBER_PAGES is set to YES; this function should be harmless
+    # when SEPARATE_MEMBER_PAGES is NO!
+    #
+    # The issue was discussed here: https://github.com/doxygen/doxygen/pull/7971
+    #
+    # A Doxygen anchor consists of a 32-byte string version of the results of
+    # passing in the stringified identifier or prototype that is being "hashed".
+    # An "a" character is then prefixed to mark it as an anchor. Depending on how
+    # the identifier is linked, it can also get a "g" prefix to mean it is part
+    # of a Doxygen group. This results in an id having either 33 or 34 bytes
+    # (containing a "g" or not). Some identifiers, eg enumerators, get twice that
+    # length to have both a unique enum + unique enumerator, and sometimes they
+    # get two "g" characters as prefix instead of one.
+    def _fixup_separate_member_pages(self, refid: str) -> str:
+        if refid:
+            parts = refid.rsplit("_", 1)
+            if len(parts) == 2 and parts[1].startswith("1"):
+                anchorid = parts[1][1:]
+                if len(anchorid) in set([33, 34]) and parts[0].endswith(anchorid):
+                    return parts[0][:-len(anchorid)] + parts[1]
+                elif len(anchorid) > 34:
+                    index = 0
+                    if anchorid.startswith('gg'):
+                        index = 1
+                        _len = 35
+                    elif anchorid.startswith('g'):
+                        _len = 34
+                    else:
+                        _len = 33
+                    if parts[0].endswith(anchorid[index:_len]):
+                        return parts[0][:-(_len - index)] + parts[1]
+
+        return refid
+
     def get_refid(self, refid: str) -> str:
+        if self.app.config.breathe_separate_member_pages:  # type: ignore
+            refid = self._fixup_separate_member_pages(refid)
         if self.app.config.breathe_use_project_refids:  # type: ignore
             return "%s%s" % (self.project_info.name(), refid)
         else:

documentation/source/directives.rst

@@ -537,3 +537,11 @@ Config Values
    documentation should be placed immediately after the brief and detailed description
    or at the end, after the returns, remarks and warnings section. Default value and
    also the legacy behavior is False.
+
+.. confval:: breathe_separate_member_pages
+
+   True or False setting to control if the input XML generated by Doxygen had the
+   Doxygen SEPARATE_MEMBER_PAGES option set to YES or NO. The Doxygen option defaults
+   to NO which generates XML that allows Breathe to resolve all references. When set
+   to YES the refid/id of elements get an extra element which Breathe tries to get rid
+   of when this setting is True.

tests/test_renderer.py

@@ -260,6 +260,7 @@ def render(app, member_def, domain=None, show_define_initializer=False,
            compound_parser=None, options=[]):
     """Render Doxygen *member_def* with *renderer_class*."""
 
+    app.config.breathe_separate_member_pages = False
     app.config.breathe_use_project_refids = False
     app.config.breathe_show_define_initializer = show_define_initializer
     app.config.breathe_debug_trace_directives = False