python-sphinx - 如何链接/引用文档中的另一个 reST 文件？

Question

我根本不知道如何链接到 reST 文件中的另一个文档。

install.rst我想在一个段落中链接一个名为我的快速入门指南的文件。我不知道我怎样才能做到这一点。

请您还可以参考一个很好的资源，我可以从中查找语法以供休息。默认的快速入门有点乏味，并且不涉及将 rest 与 sphinx 一起使用的深入讨论。

有问题的文档是：http ://todx.rtfd.io

Answer 1

要在不同的 reStructuredText (.rst) 文件之间创建链接，您可以使用 sphinx 提供的内联标记。请参阅标题交叉引用文档下的文档

在文件顶部定义其标签

.. _my-reference-label:

然后您可以使用从其他文档链接到它

:ref:`my-reference-label`.

我认为您不需要使用 intersphinx 扩展，因为它用于不同项目之间的链接。使用此方法，您可以使用上面文档链接中所述的相对路径在不同的 .rst 文件之间进行链接。

Answer 2

我使用以下方法编写指向另一个文档的链接：

:doc:`my document <../my_doc>` 

../my_doc是我的my_doc.rst文件的路径。

我的conf.py文件中也有 inter-sphinx 扩展名。

extensions = ['sphinx.ext.intersphinx']

Answer 3

简化@eme-eme 的答案，你可以这样做：

:doc:`path/to/document`

您无需将路径包含在 <> 中并提供要显示的文本。在这种情况下，引用文档的顶级标题将显示为链接。

您不需要为此进行跨狮身人面像扩展。

Answer 4

要从项目中的一个页面（.rst 文件）链接到另一个页面（不同的 .rst 文件），请使用以下内联格式：

See :ref: `topLevelHeadingofOtherPage`

例如：

See :ref:`Perform Bulk Actions`.

就是这样。我同意，在 Sphinx 指南中很难找到这些信息。这是因为它太简单了，我认为人们认为你想做一些更复杂的事情。

Answer 5

现有文件 {example.rst} 可以使用以下语法链接到：

:ref:`Optional Link text <example>`

但是，将其放入主题甚至项目符号中，行为可能会改变。因此，您可以参考最终构建的文件：

`Optional Link text <example.html>`_

这是一个很棒的指南

Answer 6

要引用其他文件，我必须在conf.py. 我从 Pillow(PIL fork) here的文档中获取了代码。

extensions = ['sphinx.ext.intersphinx']

我认为跨狮身人面像扩展对我有帮助。它链接到其他文档页面。