Merge pull request #7683 from jakobandersen/nouri_missing_reference

Re-allow NoUri from missing-reference handlers

doc/extdev/appapi.rst

@@ -230,11 +230,15 @@ connect handlers to the events.  Example:
 
 .. event:: missing-reference (app, env, node, contnode)
 
-   Emitted when a cross-reference to a Python module or object cannot be
-   resolved.  If the event handler can resolve the reference, it should return a
+   Emitted when a cross-reference to an object cannot be resolved.
+   If the event handler can resolve the reference, it should return a
    new docutils node to be inserted in the document tree in place of the node
    *node*.  Usually this node is a :class:`reference` node containing *contnode*
    as a child.
+   If the handler can not resolve the cross-reference,
+   it can either return ``None`` to let other handlers try,
+   or raise :class:`NoUri` to prevent other handlers in trying and suppress
+   a warning about this cross-reference being unresolved.
 
    :param env: The build environment (``app.builder.env``).
    :param node: The :class:`pending_xref` node to be resolved.  Its attributes

sphinx/errors.py

@@ -116,7 +116,8 @@ class PycodeError(Exception):
 
 
 class NoUri(Exception):
-    """Raised by builder.get_relative_uri() if there is no URI available."""
+    """Raised by builder.get_relative_uri() or from missing-reference handlers
+    if there is no URI available."""
     pass
 
 

sphinx/transforms/post_transforms/__init__.py

@@ -92,7 +92,8 @@ class ReferencesResolver(SphinxPostTransform):
                 # no new node found? try the missing-reference event
                 if newnode is None:
                     newnode = self.app.emit_firstresult('missing-reference', self.env,
-                                                        node, contnode)
+                                                        node, contnode,
+                                                        allowed_exceptions=(NoUri,))
                     # still not found? warn if node wishes to be warned about or
                     # we are in nit-picky mode
                     if newnode is None: