`sphinx.ext.extlinks` -- 标记以缩短外部链接¶

模块作者： Georg Brandl

在 1.0 版本加入.

此扩展旨在帮助实现一种常见模式，即有许多指向同一站点上url的外部链接，例如指向bug追踪器、版本控制web界面的链接，或者只是其他网站中的子页面的链接。它通过为基本url提供别名来实现这一点，因此您只需要在创建链接时提供子页面名称。

假设您希望在Sphinx tracker上包含许多指向问题的链接，地址 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 的链接。正如你所看到的，角色中给出的目标被替换为 基本URL 中的 %s 。

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

如果 caption 是 None ，则链接标题为完整的URL。
如果 caption 是一个字符串，则它必须恰好包含一次 %s 。在这种情况下，链接标题是用部分URL替换 %s 的 caption -- 在上面的例子中，链接标题将是 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¶

如果启用，extlinks会发出警告，如果硬编码的链接可以被extlink替换，并通过警告建议替换。

在 4.5 版本加入.

sphinx.ext.extlinks -- 标记以缩短外部链接¶