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 <fabio.utzig@nordicsemi.no>

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,33 @@ 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
+    # SEPARATE_MEMBER_PAGES is set to YES; this function should be
+    # harmless when SEPARATE_MEMBER_PAGES is NO!
+    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 a 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
+   off 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