mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
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:
committed by
Takeshi KOMIYA
parent
081e717c91
commit
fb39974486
@@ -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::
|
||||
|
||||
|
||||
Reference in New Issue
Block a user