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

模块作者： Georg Brandl

Added in version 1.0.

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

假设您希望在Sphinx跟踪器上包含许多指向问题的链接，地址为 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.的链接如您所见，角色中给出的目标被替换为 *base URL* 代替…… ``%s` 。

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

如果 caption 是 None ，链接标题是完整的URL。
如果 caption 是一个字符串，则它必须包含 %s 只有一次。在本例中，链接标题为 caption 将部分URL替换为 %s --在上面的示例中，链接标题为 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¶

如果启用，如果硬编码链接可由extlink替换，则extlink会发出警告，并通过警告建议进行替换。

Added in version 4.5.

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