Fix multi repo external references

When multi-repos are used, the resulting pending_xref's generated
from including the source code don't get a 'refdoc' property and the
intersphinx 'missing-resolver' is unable to adjust relative paths
in a way that links between different projects work.

This fixes the issue by adding a transform that fixes pending_xrefs
that match some pre-requisites, create a new copy
with the 'refdoc' property added and let intersphinx's missing-resolver
fix the URI.

Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>

breathe/directives.py

@@ -21,6 +21,8 @@
 from sphinx.writers.text import TextWriter
 from sphinx.builders.text import TextBuilder
 from sphinx.domains import cpp
+from sphinx.transforms.post_transforms import SphinxPostTransform
+from sphinx import addnodes
 
 import os
 import fnmatch
@@ -782,6 +784,38 @@ def purge_doc(self, app, env, docname):
             del self.app.env.breathe_file_state[filename]
 
 
+class DoxygenIdentifierReferenceResolver(SphinxPostTransform):
+
+    # must run before sphinx ReferenceResolver
+    default_priority = 5
+    # only resolve identifier xrefs for these domains
+    domains = set(['c', 'cpp'])
+
+    def run(self, **kwargs):
+        for node in self.document.traverse(addnodes.pending_xref):
+            if node['reftype'] != 'identifier':
+                continue
+
+            if 'refdomain' not in node or node['refdomain'] not in self.domains:
+                continue
+
+            # skip when information required by intersphinx is available already
+            if 'refdoc' in node:
+                continue
+
+            nodecopy = node.deepcopy()
+            contnode = node[0].deepcopy()
+
+            # 'refdoc' is used by intersphinx to correctly adjust relative
+            # paths when resolving external references
+            nodecopy['refdoc'] = self.env.docname
+
+            newnode = self.app.emit_firstresult('missing-reference', self.env,
+                                                nodecopy, contnode)
+            if newnode is not None:
+                node.replace_self(newnode)
+
+
 # Setup
 # -----
 
@@ -840,6 +874,8 @@ def add_directive(name):
         directive_factory.create_function_directive_container(),
         )
 
+    app.add_post_transform(DoxygenIdentifierReferenceResolver)
+
     app.add_config_value("breathe_projects", {}, True)
     app.add_config_value("breathe_default_project", "", True)
     # Provide reasonable defaults for domain_by_extension mapping. Can be overridden by users.