`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 会发出警告，并通过警告建议替换。

在 4.5 版本中添加。

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