sphinx.ext.extlinks
--缩短外部链接的标记¶
模块作者: Georg Brandl
Added in version 1.0.
此扩展旨在帮助处理具有多个指向同一站点上的URL的外部链接的常见模式,例如指向bug追踪器的链接、版本控制Web界面或其他网站中的简单子页面。它通过为基本URL提供别名来实现这一点,这样您在创建链接时只需要提供子页面名称。
假设您希望包含许多指向sphinx跟踪器问题的链接,网址为 https://github.com/sphinx-doc/sphinx/issues/{num}
. 一次又一次地输入这个URL很乏味,因此您可以使用 extlinks
避免重复你自己。
扩展名添加了一个配置值:
- extlinks¶
此配置值必须是外部站点的字典,将唯一的短别名映射到 base URL 以及一个 caption 。例如,要为上述问题创建别名,您需要添加::
extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', 'issue %s')}
现在,您可以使用别名作为新角色,例如
:issue:`123
。这将插入一个指向https://github.com/sphinx-doc/sphinx/issues/123.的链接如您所见,角色中给出的目标被替换为 *base URL* 代替…… ``%s` 。链接标题取决于元组中的第二项,即 caption :
如果 caption 是
None
,链接标题是完整的URL。如果 caption 是一个字符串,则它必须包含
%s
只有一次。在本例中,链接标题为 caption 将部分URL替换为%s
--在上面的示例中,链接标题为issue 123
。
产生一个字面意思
%
在任何一种中 base URL 或 caption ,使用%%
**extlinks = {'KnR': ('https://example.org/K%%26R/page/%s', '[K&R; page %s]')}
您还可以使用生成链接的其他角色所支持的常用“显式标题”语法。
:issue:`this issue <123>
`。在这种情况下, caption 是不相关的。在 4.0 版本发生变更: 支持用标题中的‘%s’替换。
备注
由于链接是由阅读阶段的角色生成的,因此它们看起来像普通链接,例如 linkcheck
建设者。
- extlinks_detect_hardcoded_links¶
如果启用,则当硬编码链接可由extlink替换时,extlink会发出警告,并通过警告建议替换。默认为
False
。Added in version 4.5.