如何使用 Sphinx 链接本地 Python 帮助文档

Question

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

更多详情

我有一个离线环境中的 RST 帮助文档 (index.rst)。我已经使用命令make.bat html 下载并成功构建了 Python 文档。然后我将此文档复制到 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 `'的引用

我已验证输出包含文本：

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

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

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

生成包含该行的输出：

contents      Python 文档内容     ：contents.html

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

Answer 1

在 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>

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