diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index a70c7c531a1..5aaaf9f6c30 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 diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 0cd5b0c0ce6..f6e6d7964e0 100644 --- a/sphinx/ext/intersphinx.py +++ b/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 = {{'': {(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,))) diff --git a/tests/test_ext_intersphinx.py b/tests/test_ext_intersphinx.py index 060f9eca4f9..ac49584b115 100644 --- a/tests/test_ext_intersphinx.py +++ b/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):