sphinx.ext.extlinks – 标记以缩短外部链接¶
模块作者：Georg Brandl
版本 1.0 新增。
此扩展旨在帮助解决许多外部链接指向同一站点上 URL 的常见模式，例如指向错误跟踪器、版本控制 Web 界面或只是其他网站中的子页面的链接。它通过为基本 URL 提供别名来实现此目的，因此在创建链接时，您只需提供子页面名称。
假设您想在 Sphinx 跟踪器中包含许多指向问题的链接，网址为 https://github.com/sphinx-doc/sphinx/issues/num。一遍又一遍地输入此 URL 很乏味，因此您可以使用 extlinks 来避免重复。
此扩展添加了一个配置值
- extlinks¶
- 类型:
dict[str, tuple[str, str | None]]- 默认:
{}
此配置值必须是外部站点的字典，将唯一的短别名映射到基本 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的位置。链接标题取决于元组中的第二个项目，即标题
如果标题为
None，则链接标题是完整的 URL。如果标题是字符串，则它必须只包含一个
%s。在这种情况下，链接标题是标题，其中部分 URL 替换了%s– 在上面的示例中，链接标题将是issue 123。
要在基本 URL或标题中生成字面量
%，请使用%%extlinks = {'KnR': ('https://example.org/K%%26R/page/%s', '[K&R; page %s]')}
您还可以使用其他生成链接的角色支持的常用“显式标题”语法，即
:issue:`this issue <123>`。在这种情况下，标题不相关。版本 4.0 中更改: 支持在标题中用“%s”替换。
注意
由于链接是在读取阶段从角色生成的，因此它们显示为普通链接，例如指向 linkcheck 构建器。
- extlinks_detect_hardcoded_links¶
- 类型:
bool- 默认:
False
如果启用，当硬编码链接可被 extlink 替换时，extlinks 会发出警告，并通过警告建议替换。
版本 4.5 中添加。