在 Sphinx 中链接外部文档答案

【问题标题】：Linking external documentation in Sphinx在 Sphinx 中链接外部文档
【发布时间】：2016-07-27 10:57:36
【问题描述】：

我正在尝试从我们项目的扩展文档链接到 Sphinx 中的核心文档。我试过 intersphinx，但据我所知，它只支持对象，而我们的文档没有引用对象，它只是普通的 .rst。

我已经添加了

intersphinx_mapping = {
    'project': ('http://link-to-readthedocs/index.html', None),
}

到 conf.py 并编辑了指向:ref:\`Documentation\` 和后来的:doc:\`Documentation\` 的链接。没用。

问题：

如何在 Sphinx 中为纯 .rst 文件（而非对象）从一个项目的文档链接到另一个？

编辑：我已经完成了make html，找到了我的objects.inv，但现在我想我只有在本地拥有它？我不知道我在做什么了，但是当我尝试检查 object references 时，我得到：

UserWarning: intersphinx inventory 'http://myproject.com/index.html/objects.inv' not fetchable due to <class 'urllib.error.HTTPError'>: HTTP Error 404: Not Found
  '%s: %s' % (inv, err.__class__, err))

【问题讨论】：

标签： python-sphinx

【解决方案1】：

这里首先要修复的是您包含到项目文档的基本 URL 的链接：

intersphinx_mapping = { 'project': ('http://link-to-readthedocs/index.html', None), }

根据intersphinx docs：

将唯一标识符映射到元组 (target, inventory) 的字典。每个target 是外部 Sphinx 文档集的基本 URI，可以是本地路径或 HTTP URI。 inventory 表示可以找到清单文件的位置：它可以是 None（与基本 URI 位于同一位置）或另一个本地或 HTTP URI。

因此，错误在于index.html 位于target 的末尾。它应该看起来像这样：

intersphinx_mapping = { 'project': ('http://project.readthedocs.io/en/latest', None), }

如果需要，请将 en 替换为首选文档语言，并将 latest 替换为首选 RtD 构建版本的文档。

【讨论】：