如何链接/引用文档中的另一个 reST 文件？答案

【问题标题】：How can I link/reference another reST file in the documentation?如何链接/引用文档中的另一个 reST 文件？
【发布时间】：2016-09-29 22:35:33
【问题描述】：

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

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

您能否也参考一个很棒的资源，我可以从中查找语法以供休息。默认的快速入门有点无聊，没有深入讨论如何将 rest 与 sphinx 一起使用。

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

【问题讨论】：

【解决方案1】：

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

下

在文件顶部定义其标签

.. _my-reference-label:

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

:ref:`my-reference-label`.

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

【讨论】：

使用标签时，应该是:ref:，而不是:doc:。对于:doc:，您需要指定另一个文件的名称而不是标签。
我强烈反对这种解决方案：除了初始注释外，其他任何元素都不应位于文档标题之前，因为许多渲染器都依赖于此。例如，文档开头的标签可能会破坏 sphinx 主题的导航链接。除此之外，当问题是如何链接到文档而不是文档中的随机位置时，答案过于具体。
标题标签/目标不必位于页面顶部。事实上，您可能在一个文件中有多个，例如每个部分都有一个，因此您可以直接链接到这个。我确实认为习惯上将其直接放在标题之前（例如标题或部分标题），请参阅docs.readthedocs.io/en/stable/guides/…
指向的文档位于“交叉引用任意位置”部分下。标题已经是一个锚点——所以你可以简单地引用一个标题。在此处给出的示例中，只需引用顶部标题，无需在文档前面添加引用。
@JeyesUnterwegs，您是否有任何特定的渲染器会对此有问题？此语法是标准 reStructuredText 规范的一部分，如果渲染器无法正确处理它，我会说这是渲染器错误。

【解决方案2】：

我用这个写到另一个文档的链接：

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

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

我的conf.py 文件中也有跨狮身人面像扩展名。

extensions = ['sphinx.ext.intersphinx']

【讨论】：

【解决方案3】：

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

:doc:`path/to/document`

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

你不需要跨狮身人面像扩展。

【讨论】：

【解决方案4】：

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

See :ref: `topLevelHeadingofOtherPage`

例如：

See :ref:`Perform Bulk Actions`.

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

【讨论】：

【解决方案5】：

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

:ref:`Optional Link text <example>`

但是，在主题甚至项目符号中弹出此内容，行为可能会改变。所以，你可以参考最终构建的文件：

`Optional Link text <example.html>`_

【讨论】：

您链接到的 TYPO3 备忘单有一些 TYPO3 特定的东西，用于在 TYPO3-land 中渲染文档。例如，我相信 Settings.cfg 是特定的。除此之外，这是一个很好的资源。但我会链接到一般 restructuredText / sphinx docs，例如docs.readthedocs.io/en/stable/guides/… 如果您想链接到其他手册，请查找“intersphinx”。

【解决方案6】：

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

extensions = ['sphinx.ext.intersphinx']

我认为 inter-sphinx 扩展对我有帮助。它链接到其他文档页面。

【讨论】：