Break intersphinx into a package

.ruff.toml

@@ -395,7 +395,7 @@ select = [
 "sphinx/environment/adapters/toctree.py" = ["B026"]
 
 # whitelist ``print`` for stdout messages
-"sphinx/ext/intersphinx.py" = ["T201"]
+"sphinx/ext/intersphinx/_cli.py" = ["T201"]
 
 # whitelist ``print`` for stdout messages
 "sphinx/testing/fixtures.py" = ["T201"]
@@ -503,7 +503,10 @@ exclude = [
     "sphinx/ext/mathjax.py",
     "sphinx/ext/doctest.py",
     "sphinx/ext/autosectionlabel.py",
-    "sphinx/ext/intersphinx.py",
+    "sphinx/ext/intersphinx/__init__.py",
+    "sphinx/ext/intersphinx/_cli.py",
+    "sphinx/ext/intersphinx/_load.py",
+    "sphinx/ext/intersphinx/_resolve.py",
     "sphinx/ext/duration.py",
     "sphinx/ext/imgconverter.py",
     "sphinx/ext/imgmath.py",

pyproject.toml

@@ -263,7 +263,7 @@ module = [
     "sphinx.ext.doctest",
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
-    "sphinx.ext.intersphinx",
+    "sphinx.ext.intersphinx._load",
     "sphinx.ext.napoleon.docstring",
     "sphinx.highlighting",
     "sphinx.jinja2glue",

sphinx/ext/intersphinx/__init__.py

@@ -0,0 +1,81 @@
+"""Insert links to objects documented in remote Sphinx documentation.
+
+This works as follows:
+
+* Each Sphinx HTML build creates a file named "objects.inv" that contains a
+  mapping from object names to URIs relative to the HTML set's root.
+
+* Projects using the Intersphinx extension can specify links to such mapping
+  files in the `intersphinx_mapping` config value.  The mapping will then be
+  used to resolve otherwise missing references to objects into links to the
+  other documentation.
+
+* By default, the mapping file is assumed to be at the same location as the
+  rest of the documentation; however, the location of the mapping file can
+  also be specified individually, e.g. if the docs should be buildable
+  without Internet access.
+"""
+
+from __future__ import annotations
+
+__all__ = (
+    'InventoryAdapter',
+    'fetch_inventory',
+    'fetch_inventory_group',
+    'load_mappings',
+    'normalize_intersphinx_mapping',
+    'IntersphinxRoleResolver',
+    'inventory_exists',
+    'install_dispatcher',
+    'resolve_reference_in_inventory',
+    'resolve_reference_any_inventory',
+    'resolve_reference_detect_inventory',
+    'missing_reference',
+    'IntersphinxDispatcher',
+    'IntersphinxRole',
+    'inspect_main',
+)
+
+from typing import TYPE_CHECKING
+
+import sphinx
+from sphinx.ext.intersphinx._cli import inspect_main
+from sphinx.ext.intersphinx._load import (
+    fetch_inventory,
+    fetch_inventory_group,
+    load_mappings,
+    normalize_intersphinx_mapping,
+)
+from sphinx.ext.intersphinx._resolve import (
+    IntersphinxDispatcher,
+    IntersphinxRole,
+    IntersphinxRoleResolver,
+    install_dispatcher,
+    inventory_exists,
+    missing_reference,
+    resolve_reference_any_inventory,
+    resolve_reference_detect_inventory,
+    resolve_reference_in_inventory,
+)
+from sphinx.ext.intersphinx._shared import InventoryAdapter
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_config_value('intersphinx_mapping', {}, 'env')
+    app.add_config_value('intersphinx_cache_limit', 5, '')
+    app.add_config_value('intersphinx_timeout', None, '')
+    app.add_config_value('intersphinx_disabled_reftypes', ['std:doc'], 'env')
+    app.connect('config-inited', normalize_intersphinx_mapping, priority=800)
+    app.connect('builder-inited', load_mappings)
+    app.connect('source-read', install_dispatcher)
+    app.connect('missing-reference', missing_reference)
+    app.add_post_transform(IntersphinxRoleResolver)
+    return {
+        'version': sphinx.__display_version__,
+        'env_version': 1,
+        'parallel_read_safe': True,
+    }

sphinx/ext/intersphinx/__main__.py

@@ -0,0 +1,10 @@
+"""Command line interface for the intersphinx extension."""
+
+import logging as _logging
+import sys
+
+from sphinx.ext.intersphinx import inspect_main
+
+_logging.basicConfig()
+
+raise SystemExit(inspect_main(sys.argv[1:]))

sphinx/ext/intersphinx/_cli.py

@@ -0,0 +1,44 @@
+"""This module provides contains the code for intersphinx command-line utilities."""
+
+from __future__ import annotations
+
+import sys
+
+from sphinx.ext.intersphinx._load import fetch_inventory
+
+
+def inspect_main(argv: list[str], /) -> int:
+    """Debug functionality to print out an inventory"""
+    if len(argv) < 1:
+        print("Print out an inventory file.\n"
+              "Error: must specify local path or URL to an inventory file.",
+              file=sys.stderr)
+        return 1
+
+    class MockConfig:
+        intersphinx_timeout: int | None = None
+        tls_verify = False
+        tls_cacerts: str | dict[str, str] | None = None
+        user_agent: str = ''
+
+    class MockApp:
+        srcdir = ''
+        config = MockConfig()
+
+    try:
+        filename = argv[0]
+        inv_data = fetch_inventory(MockApp(), '', filename)  # type: ignore[arg-type]
+        for key in sorted(inv_data or {}):
+            print(key)
+            inv_entries = sorted(inv_data[key].items())
+            for entry, (_proj, _ver, url_path, display_name) in inv_entries:
+                display_name = display_name * (display_name != '-')
+                print(f'    {entry:<40} {display_name:<40}: {url_path}')
+    except ValueError as exc:
+        print(exc.args[0] % exc.args[1:], file=sys.stderr)
+        return 1
+    except Exception as exc:
+        print(f'Unknown error: {exc!r}', file=sys.stderr)
+        return 1
+    else:
+        return 0