如何链接/引用文档中的另一个 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`

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

您不需要为此进行 inter-sphinx 扩展。

Answer 4

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

:ref:`Optional Link text <example>`

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

`Optional Link text <example.html>`_

Answer 5

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

See :ref: `topLevelHeadingofOtherPage`

例如：

See :ref:`Perform Bulk Actions`.

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

Answer 6

要引用标题，需要将此扩展名添加到

conf.py

:

   extensions = [
      'sphinx.ext.autosectionlabel',
   ]

然后只需使用

:ref:`Any heading in the project`

。

详情请参阅扩展说明。它也可以与 Intersphinx 结合使用。

Answer 7

@Ryszard Cetnarski 的建议对我有用，尽管确实需要几次尝试：

我的

overview.rst

文件中的相关文本：

Blah... blah...

.. _overview-database-requirements:

Database requirements
---------------------

Blah... blah...

在我的

my_python.py

文件的文档字符串中：

"""Implement some more abstract base model (table) classes.

Blah... blah...

See :ref:`overview-database-requirements` for more details.
"""

我不必启用任何额外的扩展。

Answer 8

要引用其他文件，我必须在

conf.py

中包含以下内容。我从 Pillow(PIL fork) 的文档中获取了代码here。

extensions = ['sphinx.ext.intersphinx']

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