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＆lt; python：contents＆gt;`'

我已验证输出包含文字：

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

我还通过运行以下命令验证了Python文档中的“contents”标记：

python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr 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>

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

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

1 个答案: