向另一页中的子标题或锚添加交叉引用

如何将 reST/Sphinx 页面中的交叉引用插入到同一文档集中的另一页面中的子标题或锚？

88373 次浏览
小开

表达“ reST/Sphinx”使问题的范围不明确。是关于 ReStructuredText 的 ReStructuredText，还是关于 ReStructuredText 的？因为使用 RST 的人可能会在某个时候遇到这两种情况，所以我将同时介绍这两种情况:

狮身人面像

除了可以用来链接到各种实体(如类(:class:))的特定于域的指令之外，还有通用的 :ref:指令，文档化的 给你。他们举了一个例子:

    .. _my-reference-label:


Section to cross-reference
--------------------------


This is the text of the section.


It refers to the section itself, see :ref:`my-reference-label`.

虽然 RST 提供的通用超链接机制在 Sphinx 中确实有效，但文档建议在使用 Sphinx 时不要使用它:

通过标准的 ReStructuredText 链接(如 Section title _)使用 ref 是建议的，因为它可以跨文件工作，当节标题发生变化时，对于所有支持交叉引用的构建器都可以使用 ref。

一般而言，RST

将 RST 文件转换为 HTML 的工具不一定具有 收藏品的概念。例如，如果依赖 github 将 RST 文件转换为 HTML，或者使用 rst2html这样的命令行工具，就会出现这种情况。不幸的是，用于获得所需结果的各种方法因所使用的工具而异。例如，如果您使用 rst2html，并希望文件 A.rst链接到文件 other.rst中名为“ Section”的部分，并希望最终的 HTML 在浏览器中工作，那么 A.rst将包含:

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

你必须链接到最终的 HTML 文件，你必须知道什么样的 id给这一节将。如果希望对通过 github 提供的文件执行相同操作:

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

在这里，你也需要知道的 id给的部分。但是，您可以链接到 RST 文件，因为只有在访问 RST 文件时才会创建 HTML。(在撰写本答案时，不允许直接访问 HTML。)

一个完整的例子是可用的 给你。

小开

新的，更好的2016年答案！

自动分割延伸部分可以让您轻松地完成这项工作。

=============
Some Document
=============




Internal Headline
=================

然后，之后..。

===============
Some Other Doc
===============




A link-  :ref:`Internal Headline`

这个扩展是内置的，所以您只需编辑 conf.py

extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]

唯一需要注意的是，现在无法在 doc 集合中复制内部标题。(值了)

小开

例如:

Hey, read the :ref:`Installation:Homebrew` section.

其中 Homebrew是一个名为 Installation.rst的不同文档中的一个部分。

这使用了 自动切割功能自动切割功能，因此需要用以下代码编辑 config.py:

extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
小开

在 Sphinx3.0.3中，唯一适合我的解决方案是 :any:(参见 https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything)。 假设一个文档有这样一个部分:

.. _my-section:


My Section
----------


Lorem ipsum blablabla

然后，另一个文档可以使用以下片段来创建链接:

See :any:`my-section` for the details
小开

我一直在努力使这个工作，我发现实际的符号是 :ref:'{dir-path}/Installation:Homebrew'，其中 {dir-path}是从 config.py 存在的地方到 Installation.rst 的相对路径

小开

添加的行为描述让我感到困惑。

节标题必须与前面的文件名(概述)一起引用:

概述:

    ************
API Overview
************

首页:

    :ref:`overview:API Overview`

但是，当引用链接时，文件名(这里的常量)不能在那里:

常数:

    .. _section-constants:


*******************
Enums and Constants
*******************

首先:

    :ref:`section-constants`

此外，为了实现这一点，必须启用扩展“ autosectionlabel”:

Py:

    extensions = [
...
"sphinx.ext.autosectionlabel"
]

提交答案