:模式:sphinx.ext.extlinks–标记以缩短外部链接¶
模块作者: Georg Brandl
Added in version 1.0.
此扩展旨在帮助实现一种常见模式,即有许多指向同一站点上url的外部链接,例如指向bug追踪器、版本控制web界面的链接,或者只是其他网站中的子页面的链接。它通过为基本url提供别名来实现这一点,因此您只需要在创建链接时提供子页面名称。
假设您希望在Sphinx tracker上包含许多指向问题的链接,地址:samp:https://github.com/sphinx-doc/sphinx/issues/{num}。一次又一次地键入此URL是很乏味的,因此可以使用:mod:`~sphinx.ext.extlinks`为了避免重复你自己。
该插件添加了一个配置值:
- 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 alias for the above mentioned issues, you would add
extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', '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 caption:
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 beissue 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.在 4.0 版本发生变更: Support to substitute by ‘%s’ in the caption.
备注
由于链接是从阅读阶段的角色生成的,因此它们看起来像是普通链接,例如“linkcheck”构建器。
- extlinks_detect_hardcoded_links¶
If enabled, extlinks emits a warning if a hardcoded link is replaceable by an extlink, and suggests a replacement via warning. It defaults to
False
.Added in version 4.5.