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,9 +364,14 @@ 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)
+        resolve_self = self.env.config.intersphinx_resolve_self
+        self_referential = bool(resolve_self) and resolve_self == inventory
+
+        if not self_referential:
             if inventory and not inventory_exists(self.env, inventory):
                 self._emit_warning(
-                __('inventory for external cross-reference not found: %r'), inventory
+                    __('inventory for external cross-reference not found: %r'),
+                    inventory,
                 )
                 return [], []
 
@@ -453,6 +458,10 @@ class IntersphinxRole(SphinxRole):
             self.content,
         )
 
+        if not self_referential:
+            # We do the intersphinx resolution by inserting our
+            # 'intersphinx' and 'inventory' attributes into the nodes.
+            # Only do this when it is an external reference.
             for node in result:
                 if isinstance(node, pending_xref):
                     node['intersphinx'] = True