2

如何让我的 Sphinx RST 文件包含指向“contents.html”Python 帮助页面的链接？

更多细节

我在离线环境中有一个 RST 帮助文档 ( index.rst )。我已经下载并使用命令成功构建了 Python 文档make.bat html。然后我将此文档复制到 C:\Temp\PyDoc。

然后我更新了我的 conf.py 文件以包含以下 Intersphinx 映射：

intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}

然后，在我的index.rst文件中，我有类似的内容：

Contents:

.. toctree::
   :maxdepth: 1

   :ref:`Python <python:contents>`

Python链接已从生成的文档中删除，并带有警告消息：

警告：toctree 包含对不存在文档 ':ref:`Python <python:contents>` 的引用

我已验证输出包含以下文本：

从 C:/Temp/PyDoc/objects.inv 加载 intersphinx 库存...

我还通过运行验证了 Python 文档中存在“内容”标签：

python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr contents

生成包含以下行的输出：

内容 Python 文档内容：contents.html

有谁知道如何从我的 RST 文件中引用这个外部文档？

4

1 回答 1

2

在 intersphinx 的配置中，dict的键值是一个tuple，它由逗号分隔的值组成，而不是冒号分隔的。

intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}

编辑

toctree条目需要一个有效的目标，它可以是相对于当前文件的文件，也可以是从您conf.py所在的文档根目录开始的绝对文件。目标也可能是 URL。我怀疑你做的 HTML 不是上面的，所以你需要把它移到 Sphinx 可以找到的地方。

语法应该用于文档，而不是 Python 对象，因为页面是目录。我没有尝试这个例子，因为我没有下载和构建 Python 文档，所以我怀疑它会起作用。

.. toctree::
    :maxdepth: 1

    :doc:`Python <python:contents>`

或者您可以只使用 URL（或类似的相对或绝对目标）。这适用于我的完全限定 URL。

.. toctree::
    :maxdepth: 1

    Python <https://docs.python.org/3/contents.html>

最后你可以尝试一个包含，但我认为这不是你真正想要的。

于 2018-05-26T07:53:47.353 回答