diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst index 221b79d99..e1d729f5c 100644 --- a/doc/usage/extensions/extlinks.rst +++ b/doc/usage/extensions/extlinks.rst @@ -23,33 +23,29 @@ The extension adds a config value: .. confval:: extlinks This config value must be a dictionary of external sites, mapping unique - short alias names to a *base URL* and a *caption*. For example, to create an + short alias names to a base URL and a *prefix*. For example, to create an alias for the above mentioned issues, you would add :: extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', - 'issue %s')} + 'issue ')} Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123. - As you can see, the target given in the role is substituted in the *base URL* + As you can see, the target given in the role is substituted in the base URL in the place of ``%s``. - The link caption depends on the second item in the tuple, the *caption*: + The link *caption* depends on the second item in the tuple, the *prefix*: - - If *caption* is ``None``, the link caption is the full URL. - - If *caption* is a string, then it must contain ``%s`` exactly once. In - this case the link caption is *caption* with the partial URL substituted - for ``%s`` -- in the above example, the link caption would be + - If the prefix is ``None``, the link caption is the full URL. + - If the prefix is the empty string, the link caption is the partial URL + given in the role content (``123`` in this case.) + - If the prefix is a non-empty string, the link caption is the partial URL, + prepended by the prefix -- in the above example, the link caption would be ``issue 123``. - To produce a literal ``%`` in either *base URL* or *caption*, use ``%%``:: - - extlinks = {'KnR': ('https://example.org/K%%26R/page/%s', - '[K&R; page %s]')} - You can also use the usual "explicit title" syntax supported by other roles that generate links, i.e. ``:issue:`this issue <123>```. In this case, the - *caption* is not relevant. + *prefix* is not relevant. .. note:: diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py index 0af335686..d82c0378b 100644 --- a/sphinx/ext/extlinks.py +++ b/sphinx/ext/extlinks.py @@ -7,25 +7,22 @@ This adds a new config value called ``extlinks`` that is created like this:: - extlinks = {'exmpl': ('https://example.invalid/%s.html', caption), ...} + extlinks = {'exmpl': ('https://example.invalid/%s.html', prefix), ...} Now you can use e.g. :exmpl:`foo` in your documents. This will create a link to ``https://example.invalid/foo.html``. The link caption depends on - the *caption* value given: + the *prefix* value given: - If it is ``None``, the caption will be the full URL. - - If it is a string, it must contain ``%s`` exactly once. In this case the - caption will be *caption* with the role content substituted for ``%s``. + - If it is a string (empty or not), the caption will be the prefix prepended + to the role content. 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 @@ -34,52 +31,37 @@ from docutils.parsers.rst.states import Inliner 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(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 make_link_role(base_url: str, prefix: str) -> RoleFunction: 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) - full_url = base_url % part + 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 if not has_explicit_title: - if caption is None: + if prefix is None: title = full_url else: - title = caption % part + title = prefix + part pnode = nodes.reference(title, title, internal=False, refuri=full_url) return [pnode], [] return role def setup_link_roles(app: Sphinx) -> None: - for name, (base_url, caption) in app.config.extlinks.items(): - app.add_role(name, make_link_role(name, base_url, caption)) + for name, (base_url, prefix) in app.config.extlinks.items(): + app.add_role(name, make_link_role(base_url, prefix)) def setup(app: Sphinx) -> Dict[str, Any]: