diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py index e846c66b8de..0af335686c4 100644 --- a/sphinx/ext/extlinks.py +++ b/sphinx/ext/extlinks.py @@ -19,10 +19,13 @@ You can also give an explicit caption, e.g. :exmpl:`Foo `. + Both, the url string and the caption string must escape ``%`` as ``%%``. + :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ +import warnings from typing import Any, Dict, List, Tuple from docutils import nodes, utils @@ -31,36 +34,44 @@ import sphinx from sphinx.application import Sphinx +from sphinx.deprecation import RemovedInSphinx60Warning from sphinx.util.nodes import split_explicit_title from sphinx.util.typing import RoleFunction -def make_link_role(base_url: str, caption: str) -> RoleFunction: +def make_link_role(name: str, base_url: str, caption: str) -> RoleFunction: + # Check whether we have base_url and caption strings have an '%s' for + # expansion. If not, fall back the the old behaviour and use the string as + # a prefix. + # Remark: It is an implementation detail that we use Pythons %-formatting. + # So far we only expose ``%s`` and require quoting of ``%`` using ``%%``. + try: + base_url % 'dummy' + except (TypeError, ValueError): + warnings.warn('extlinks: Sphinx-6.0 will require base URL to ' + 'contain exactly one \'%s\' and all other \'%\' need ' + 'to be escaped as \'%%\'.', RemovedInSphinx60Warning) + base_url = base_url.replace('%', '%%') + '%s' + if caption is not None: + try: + caption % 'dummy' + except (TypeError, ValueError): + warnings.warn('extlinks: Sphinx-6.0 will require a caption string to ' + 'contain exactly one \'%s\' and all other \'%\' need ' + 'to be escaped as \'%%\'.', RemovedInSphinx60Warning) + caption = caption.replace('%', '%%') + '%s' + def role(typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: Dict = {}, content: List[str] = [] ) -> Tuple[List[Node], List[system_message]]: text = utils.unescape(text) has_explicit_title, title, part = split_explicit_title(text) - try: - full_url = base_url % part - except (TypeError, ValueError): - inliner.reporter.warning( - 'unable to expand %s extlink with base URL %r, please make ' - 'sure the base contains \'%%s\' exactly once' - % (typ, base_url), line=lineno) - full_url = base_url + part + full_url = base_url % part if not has_explicit_title: if caption is None: title = full_url else: - try: - title = caption % part - except (TypeError, ValueError): - inliner.reporter.warning( - 'unable to expand %s extlink with caption %r, please make ' - 'sure the caption contains \'%%s\' exactly once' - % (typ, caption), line=lineno) - title = caption + part + title = caption % part pnode = nodes.reference(title, title, internal=False, refuri=full_url) return [pnode], [] return role @@ -68,7 +79,7 @@ def role(typ: str, rawtext: str, text: str, lineno: int, def setup_link_roles(app: Sphinx) -> None: for name, (base_url, caption) in app.config.extlinks.items(): - app.add_role(name, make_link_role(base_url, caption)) + app.add_role(name, make_link_role(name, base_url, caption)) def setup(app: Sphinx) -> Dict[str, Any]: