From 5dd63cdf2ffc534750b06ca9785413aae7927107 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 22 Jan 2022 14:09:39 +0100 Subject: [PATCH 1/2] intersphinx, deprecate old explicit inventory specification --- sphinx/ext/intersphinx.py | 9 ++++++++- tests/test_ext_intersphinx.py | 1 + 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 2f8ab2588e7..e1efc05b011 100644 --- a/sphinx/ext/intersphinx.py +++ b/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:]) diff --git a/tests/test_ext_intersphinx.py b/tests/test_ext_intersphinx.py index b2ad8afe52f..5dede56f7af 100644 --- a/tests/test_ext_intersphinx.py +++ b/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') From 048af4564c6ce374e4f453123fe40ccaf957d0d0 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 22 Jan 2022 14:26:44 +0100 Subject: [PATCH 2/2] intersphinx, use external in own docs --- doc/internals/release-process.rst | 15 ++++++++------- doc/tutorial/deploying.rst | 6 +++--- doc/usage/configuration.rst | 5 +++-- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst index 4e34debfba9..f30f7692325 100644 --- a/doc/internals/release-process.rst +++ b/doc/internals/release-process.rst @@ -76,12 +76,12 @@ 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. @@ -89,16 +89,17 @@ 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 -`) for more details. +``PYTHONWARNINGS=default`` +(see the :external+python:ref:`Python docs on configuring warnings +`) for more details. Release procedures ------------------ diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 85fc6643ab5..2f695f2738a 100644 --- a/doc/tutorial/deploying.rst +++ b/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 `, which is loosely based on this one. +way of getting started is to follow :external+readthedocs:doc:`the RTD +tutorial `, which is loosely based on this one. You can publish your sources on GitHub as explained :ref:`in the previous section `, 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 diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 737e2282330..d4a8836c598 100644 --- a/doc/usage/configuration.rst +++ b/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 ` for details). + that is understood by the ``requests`` library + (see :external+requests:ref:`requests 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