IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

sphinx.ext.extlinks: Clarify escaping of `%`

Browse Source 
We use Pythons %-formatting, so literal ``%`` must be escaped as ``%%``.
Clarify this behaviour for the caption and base URL strings.
This commit is contained in:
Merry Bass 2021-04-09 12:24:15 +02:00 committed by Takeshi KOMIYA
parent fb39974486
commit ef1747f03a
1 changed files with 7 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/usage/extensions/extlinks.rst
View File

@ -23,7 +23,7 @@ The extension adds a config value:
.. confval:: extlinks .. confval:: extlinks
This config value must be a dictionary of external sites, mapping unique 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 *caption*. For example, to create an
alias for the above mentioned issues, you would add :: alias for the above mentioned issues, you would add ::
extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
@ -31,7 +31,7 @@ The extension adds a config value:
Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This 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. 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``. 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 *caption*:
@ -42,6 +42,11 @@ The extension adds a config value:
for ``%s`` -- in the above example, the link caption would be for ``%s`` -- in the above example, the link caption would be
``issue 123``. ``issue 123``.
To produce a literal ``%`` in either *base URL* or *caption*, use ``%%``::
extlinks = {'wikipedia': ('https://en.wikipedia.org/w/index.php?search=%s&title=Special%%3ASearch&fulltext=Search&ns0=1'
'Search %s on Wikipedia')}
You can also use the usual "explicit title" syntax supported by other roles 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 that generate links, i.e. ``:issue:`this issue <123>```. In this case, the
*caption* is not relevant. *caption* is not relevant.