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

模块作者：Georg Brandl

1.0 新版功能.

此扩展旨在帮助实现具有指向同一站点上的URL的许多外部链接的常见模式，例如，链接到错误跟踪器，版本控制Web界面，或简单的其他网站的子页面。它通过为基本URL提供别名来实现，因此您只需在创建链接时提供子页面名称。

假设您希望在Sphinx跟踪器中包含许多问题链接，请访问 https://github.com/sphinx-doc/sphinx/issues/num 。 一次又一次地输入这个URL很乏味，所以你可以使用 extlinks 来避免重复自己。

扩展名添加配置值:

extlinks

此配置值必须是外部站点的字典，将唯一的短别名映射到基本URL和 prefix 。例如，要为上述问题创建别名，您可以添加:

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue ')}

现在，您可以将别名用作新角色，例如 :issue:`123` 。然后，这会将链接插入 https://github.com/sphinx-doc/sphinx/issues/123 。正如您所看到的，角色中给出的目标在基本URL中替换为 %s。

链接 caption 取决于元组中的第二项，prefix:

• 如果前缀是 None ，则链接标题是完整的URL。

• 如果前缀是空字符串，则链接标题是角色内容中给出的部分URL（在这种情况下为 123 。）

• 如果前缀是非空字符串，则链接标题是前缀前缀的部分URL - 在上面的示例中，链接标题将是 issue 123 。

您还可以使用生成链接的其他角色支持的通常的“显式标题”语法，即 :issue:`this issue <123>` 。在这种情况下，prefix 不相关。

注解

由于链接是从阅读阶段的角色生成的，因此它们作为普通链接出现在例如 linkcheck 构建器。