sphinx.ext.extlinks: Allow `%s` in link caption string

Tweak syntax of extlinks to also allow ``%s`` in the link caption part.
Like for the base URL ``%s`` will be substituted with the content of the
role.  This allows configurations like

    extlinks = {'quarter': ('https://example.org/quaters/%s',
                          '%s. quarter')}

with ``:quarter:`2``` getting replaced by a link titled `2. quarter`.

The requirement for the caption string is to be either None or contain
exactly one ``%s``.  If neither is the case, then we emit a warning and
fall back to the old behaviour which is concatenating the caption string
with the role content.
This commit is contained in:
Merry Bass
2021-02-15 18:59:35 +00:00
committed by Takeshi KOMIYA
parent 081e717c91
commit fb39974486
2 changed files with 24 additions and 18 deletions

View File

@@ -23,29 +23,28 @@ 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 *prefix*. For example, to create an
short alias names to a base URL and a *caption*. 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 ')}
'issue %s')}
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
in the place of ``%s``.
The link *caption* depends on the second item in the tuple, the *prefix*:
The link caption depends on the second item in the tuple, the *caption*:
- 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
- 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
``issue 123``.
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
*prefix* is not relevant.
*caption* is not relevant.
.. note::