`sphinx.ext.extlinks` – 用于缩短外部链接的标记¶

模块作者： Georg Brandl

Added in version 1.0.

这个扩展旨在帮助处理常见模式,即有许多外部链接指向同一个网站上的URL,例如指向错误追踪器、版本控制网页接口或其他网站中的子页面.它通过提供基本URL的别名来实现这一点,因此在创建链接时只需提供子页面名称.

假设您想在 Sphinx 追踪器中包含许多指向问题的链接,格式为 https://github.com/sphinx-doc/sphinx/issues/num .反复输入这个 URL 是很麻烦的,因此您可以使用 extlinks 来避免重复.

该扩展添加了一个配置值:

extlinks¶

此配置值必须是一个外部站点的字典,将唯一的短别名映射到 基础 URL 和标题.例如,要为上述提到的问题创建别名,您可以添加

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

现在,您可以将别名用作新角色,例如``:issue:123``` .这会插入一个链接到 https://github.com/sphinx-doc/sphinx/issues/123.正如您所看到的,角色中给定的目标替换了 基本 URL 中的 %s .

链接标题依赖于元组中的第二个项,即 caption:

如果 caption 为 None ,链接标题将是完整的 URL.
如果 caption 是一个字符串,那么它必须恰好包含 %s 一次.在这种情况下,链接标题为 caption,将部分 URL 替换为 %s ——在上面的示例中,链接标题将是 issue 123 .

要在 基本 URL 或标题中生成文字 % ,请使用 %%

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

您也可以使用其他生成链接的角色支持的常规”显式标题”语法,即``:issue:此问题 <123>``` .在这种情况下,*标题*是不相关的.

在 4.0 版本发生变更: 支持在标题中使用’%s’进行替换.

备注

由于链接是在阅读阶段根据角色生成的,因此它们在例如 linkcheck 构建器中呈现为普通链接.

extlinks_detect_hardcoded_links¶: 如果启用,当硬编码链接可以被外部链接替代时,extlinks会发出警告,并通过警告建议替代方案. 默认值为 False .

Added in version 4.5.

sphinx.ext.extlinks – 用于缩短外部链接的标记¶