Add the `intersphinx_resolve_self` option (#13291)

Co-authored-by: Jakob Lykke Andersen <Jakob@caput.dk>

CHANGES.rst

@@ -101,6 +101,9 @@ Features added
 * #13105: Introduce the :rst:role:`py:deco` role to cross-reference decorator
   functions and methods in the Python domain.
   Patch by Adam Turner.
+* #9169: Add the :confval:`intersphinx_resolve_self` option
+  to resolve an intersphinx reference to the current project.
+  Patch by Jakob Lykke Andersen and Adam Turner.
 
 Bugs fixed
 ----------

doc/usage/extensions/intersphinx.rst

@@ -133,6 +133,33 @@ linking:
                   ('../../otherbook/build/html/objects.inv', None)),
       }
 
+.. confval:: intersphinx_resolve_self
+   :type: :code-py:`str`
+   :default: :code-py:`''`
+
+   If provided, :confval:`!intersphinx_resolve_self` overrides intersphinx's
+   resolution mechanism to resolve all references to the current project,
+   rather than an external reference.
+   This is useful when documentation is shared between projects,
+   with the 'upstream' or 'parent' project using intersphinx-style references
+   in its documentation.
+   For example, a project such as *Astropy* might set:
+
+   .. code-block:: python
+
+      intersphinx_resolve_self = 'astropy'
+
+   Projects re-using *Astropy*'s documentation or inheriting their docstrings
+   would then configure their :confval:`!intersphinx_mapping` with
+   an :code-py:`'astropy'` key, pointing to *astropy*'s :file:`objects.inv`.
+   For example:
+
+   .. code-block:: python
+
+      intersphinx_mapping = {
+          'astropy': ('https://docs.astropy.org/en/stable/', None),
+      }
+
 .. confval:: intersphinx_cache_limit
    :type: :code-py:`int`
    :default: :code-py:`5` (five days)

sphinx/ext/intersphinx/__init__.py

@@ -64,6 +64,7 @@ if TYPE_CHECKING:
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value('intersphinx_mapping', {}, 'env', types=frozenset({dict}))
+    app.add_config_value('intersphinx_resolve_self', '', 'env', types=frozenset({str}))
     app.add_config_value('intersphinx_cache_limit', 5, '', types=frozenset({int}))
     app.add_config_value(
         'intersphinx_timeout', None, '', types=frozenset({int, float, type(None)})

sphinx/ext/intersphinx/_resolve.py

@@ -364,11 +364,16 @@ class IntersphinxRole(SphinxRole):
     def run(self) -> tuple[list[Node], list[system_message]]:
         assert self.name == self.orig_name.lower()
         inventory, name_suffix = self.get_inventory_and_name_suffix(self.orig_name)
-        if inventory and not inventory_exists(self.env, inventory):
+        resolve_self = self.env.config.intersphinx_resolve_self
-            self._emit_warning(
+        self_referential = bool(resolve_self) and resolve_self == inventory
-                __('inventory for external cross-reference not found: %r'), inventory
+
-            )
+        if not self_referential:
-            return [], []
+            if inventory and not inventory_exists(self.env, inventory):
+                self._emit_warning(
+                    __('inventory for external cross-reference not found: %r'),
+                    inventory,
+                )
+                return [], []
 
         domain_name, role_name = self._get_domain_role(name_suffix)
 
@@ -453,10 +458,14 @@ class IntersphinxRole(SphinxRole):
             self.content,
         )
 
-        for node in result:
+        if not self_referential:
-            if isinstance(node, pending_xref):
+            # We do the intersphinx resolution by inserting our
-                node['intersphinx'] = True
+            # 'intersphinx' and 'inventory' attributes into the nodes.
-                node['inventory'] = inventory
+            # Only do this when it is an external reference.
+            for node in result:
+                if isinstance(node, pending_xref):
+                    node['intersphinx'] = True
+                    node['inventory'] = inventory
 
         return result, messages