[WIP] intersphinx, deprecate old explicit inventory specification

doc/internals/release-process.rst

@@ -76,29 +76,30 @@ Sphinx 2.x:
 
 * Sphinx 2.x will contain a backwards-compatible replica of the function
   which will raise a ``RemovedInSphinx40Warning``.
-  This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
-  will not get displayed by default.
+  This is a subclass of :external+python::exc:`PendingDeprecationWarning`,
+  i.e., it will not get displayed by default.
 
 * Sphinx 3.x will still contain the backwards-compatible replica, but
   ``RemovedInSphinx40Warning`` will be a subclass of
-  :exc:`python:DeprecationWarning` then, and gets displayed by default.
+  :external+python:exc:`DeprecationWarning` then, and gets displayed by default.
 
 * Sphinx 4.0 will remove the feature outright.
 
 Deprecation warnings
 ~~~~~~~~~~~~~~~~~~~~
 
 Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default, if
-:envvar:`python:PYTHONWARNINGS` is not set.  Therefore you can disable them
-using:
+:external+python:envvar:`PYTHONWARNINGS` is not set.  Therefore you can disable
+them using:
 
 * ``PYTHONWARNINGS= make html`` (Linux/Mac)
 * ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
 * ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
 
 But you can also explicitly enable the pending ones using e.g.
-``PYTHONWARNINGS=default`` (see the :ref:`Python docs on configuring warnings
-<python:describing-warning-filters>`) for more details.
+``PYTHONWARNINGS=default``
+(see the :external+python:ref:`Python docs on configuring warnings
+<describing-warning-filters>`) for more details.
 
 Release procedures
 ------------------

doc/tutorial/deploying.rst

@@ -160,11 +160,11 @@ Read the Docs
 ~~~~~~~~~~~~~
 
 `Read the Docs`_ offers integration with both GitHub and GitLab. The quickest
-way of getting started is to follow :doc:`the RTD
-tutorial <readthedocs:tutorial/index>`, which is loosely based on this one.
+way of getting started is to follow :external+readthedocs:doc:`the RTD
+tutorial <tutorial/index>`, which is loosely based on this one.
 You can publish your sources on GitHub as explained :ref:`in the previous
 section <publishing-sources>`, then skip directly to
-:ref:`readthedocs:tutorial/index:Sign up for Read the Docs`.
+:external+readthedocs:ref:`tutorial/index:Sign up for Read the Docs`.
 If you choose GitLab instead, the process is similar.
 
 GitHub Pages

doc/usage/configuration.rst

@@ -2664,8 +2664,9 @@ Options for the linkcheck builder
      A regular expression that matches a URI.
    *auth_info*
      Authentication information to use for that URI. The value can be anything
-     that is understood by the ``requests`` library (see :ref:`requests
-     Authentication <requests:authentication>` for details).
+     that is understood by the ``requests`` library
+     (see :external+requests:ref:`requests Authentication <authentication>` for
+     details).
 
    The ``linkcheck`` builder will use the first matching ``auth_info`` value
    it can find in the :confval:`linkcheck_auth` list, so values earlier in the

sphinx/ext/intersphinx.py

@@ -195,7 +195,7 @@ def fetch_inventory(app: Sphinx, uri: str, inv: Any) -> Any:
 
 
 def fetch_inventory_group(
-    name: str, uri: str, invs: Any, cache: Any, app: Any, now: float
+        name: str, uri: str, invs: Any, cache: Any, app: Any, now: float
 ) -> bool:
     cache_time = now - app.config.intersphinx_cache_limit * 86400
     failures = []
@@ -461,6 +461,11 @@ def resolve_reference_detect_inventory(env: BuildEnvironment,
     node['reftarget'] = newtarget
     res_inv = resolve_reference_in_inventory(env, inv_name, node, contnode)
     node['reftarget'] = target
+    if res_inv is not None and env.config.intersphinx_warn_on_deprecated_inv_spec:
+        msg = __('intersphinx inventory specification format'
+                 ' ":role:`invName:target`" is deprecated.'
+                 ' Use the "external" role instead, e.g., ":external+invName:role:`target`".')
+        logger.warning(msg, location=node)
     return res_inv
 
 
@@ -638,6 +643,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('intersphinx_cache_limit', 5, False)
     app.add_config_value('intersphinx_timeout', None, False)
     app.add_config_value('intersphinx_disabled_reftypes', [], True)
+    app.add_config_value('intersphinx_warn_on_deprecated_inv_spec', True, False)
     app.connect('config-inited', normalize_intersphinx_mapping, priority=800)
     app.connect('builder-inited', load_mappings)
     app.connect('source-read', install_dispatcher)
@@ -687,6 +693,7 @@ def warn(self, msg: str) -> None:
 
 if __name__ == '__main__':
     import logging as _logging
+
     _logging.basicConfig()
 
     inspect_main(argv=sys.argv[1:])

tests/test_ext_intersphinx.py

@@ -46,6 +46,7 @@ def set_config(app, mapping):
     app.config.intersphinx_mapping = mapping
     app.config.intersphinx_cache_limit = 0
     app.config.intersphinx_disabled_reftypes = []
+    app.config.intersphinx_warn_on_deprecated_inv_spec = True
 
 
 @mock.patch('sphinx.ext.intersphinx.InventoryFile')