Deprecate legacy intersphinx_mapping format (#11247)

This format was made obsolete in Sphinx 1.0, but never formally deprecated.

Author: AA-Turner

doc/usage/extensions/intersphinx.rst

@@ -63,17 +63,7 @@ linking:
    When fetching remote inventory files, proxy settings will be read from
    the ``$HTTP_PROXY`` environment variable.
 
-   **Old format for this config value**
-
-   This is the format used before Sphinx 1.0.  It is still recognized.
-
-   A dictionary mapping URIs to either ``None`` or an URI.  The keys are the
-   base URI of the foreign Sphinx documentation sets and can be local paths or
-   HTTP URIs.  The values indicate where the inventory file can be found: they
-   can be ``None`` (at the same location as the base URI) or another local or
-   HTTP URI.
-
-   **New format for this config value**
+   **Format**
 
    .. versionadded:: 1.0
 
@@ -136,6 +126,28 @@ linking:
                   ('../../otherbook/build/html/objects.inv', None)),
       }
 
+   **Old format for this config value**
+
+   .. deprecated:: 6.2
+
+   .. RemovedInSphinx80Warning
+
+   .. caution:: This is the format used before Sphinx 1.0.
+                It is deprecated and will be removed in Sphinx 8.0.
+
+   A dictionary mapping URIs to either ``None`` or an URI.  The keys are the
+   base URI of the foreign Sphinx documentation sets and can be local paths or
+   HTTP URIs.  The values indicate where the inventory file can be found: they
+   can be ``None`` (at the same location as the base URI) or another local or
+   HTTP URI.
+
+   Example:
+
+   .. code:: python
+
+      intersphinx_mapping = {'https://docs.python.org/': None}
+
+
 .. confval:: intersphinx_cache_limit
 
    The maximum number of days to cache remote inventories.  The default is

sphinx/ext/intersphinx.py

@@ -617,7 +617,15 @@ def normalize_intersphinx_mapping(app: Sphinx, config: Config) -> None:
                     continue
             else:
                 # old format, no name
+                # xref RemovedInSphinx80Warning
                 name, uri, inv = None, key, value
+                logger.warning(
+                    "The pre-Sphinx 1.0 'intersphinx_mapping' format is "
+                    "deprecated and will be removed in Sphinx 8. Update to the "
+                    "current format as described in the documentation. "
+                    f"Hint: \"intersphinx_mapping = {{'<name>': {(uri, inv)!r}}}\"."
+                    "https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping",  # NoQA: E501
+                )
 
             if not isinstance(inv, tuple):
                 config.intersphinx_mapping[key] = (name, (uri, (inv,)))

tests/test_ext_intersphinx.py

@@ -390,7 +390,10 @@ def test_load_mappings_warnings(tempdir, app, status, warning):
     # load the inventory and check if it's done correctly
     normalize_intersphinx_mapping(app, app.config)
     load_mappings(app)
-    assert warning.getvalue().count('\n') == 1
+    warnings = warning.getvalue().splitlines()
+    assert len(warnings) == 2
+    assert "The pre-Sphinx 1.0 'intersphinx_mapping' format is " in warnings[0]
+    assert 'intersphinx identifier 12345 is not string. Ignored' in warnings[1]
 
 
 def test_load_mappings_fallback(tempdir, app, status, warning):