Deprecate legacy ``intersphinx_mapping`` format (#11247)

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

1 files changed, 23 insertions, 11 deletions

diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst
index a70c7c531..5aaaf9f6c 100644
--- a/doc/usage/extensions/intersphinx.rst
+++ b/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