`sphinx.ext.extlinks` – 简化外部链接标记¶

模块作者：Georg Brandl

版本 1.0 中新增。

此扩展旨在帮助处理常见的模式，即拥有许多指向同一站点上的 URL 的外部链接，例如指向错误跟踪器、版本控制 Web 接口或其他网站中的子页面的链接。它通过为基本 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 的位置。

链接标题取决于元组中的第二个项目，即标题

如果标题为 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¶: 如果启用，则如果硬编码链接可以通过 extlink 替换，则 extlinks 会发出警告，并通过警告建议替换。默认为 False。

版本 4.5 中新增。

sphinx.ext.extlinks – 简化外部链接标记¶