在另一个页面中添加对子标题或锚点的交叉引用

Posted 2023-02-24

【中文标题】在另一个页面中添加对子标题或锚点的交叉引用

【英文标题】：Adding a cross-reference to a subheading or anchor in another page

【发布时间】：2013-03-01 22:06:18

【问题描述】：

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

【问题讨论】：

How to make an internal hyper link in sphinx documentation的可能重复

【参考方案1】：

“reST/Sphinx”表达使问题的范围不清楚。它是关于 reStructuredText 的一般 和 Sphinx，还是 仅 关于 reStructuredText 在 Sphinx 中使用的（而不是一般的 reStructuredText）？我将同时介绍这两种情况，因为使用 RST 的人在某些时候可能会遇到这两种情况：

狮身人面像

除了可用于链接到各种实体（如类 (:class:) 的特定于域的指令外，还有通用的 :ref: 指令，文档化为 here。他们举了这个例子：

    .. _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 链接上使用 ref，而不是指向节的标准 reStructuredText 链接（例如 Section title_），因为它适用于文件、节标题更改时以及支持交叉引用的所有构建器。

一般情况下的RST

将 RST 文件转换为 html 的工具不一定有 collection 的概念。例如，如果您依赖 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。）

一个完整的例子是可用的here。

【讨论】：

比问题所有者接受的答案要好得多。 （尽管RST, in General 是令人失望的消息！）

Sphinx .. _my-reference-label: 方法的一个缺点是my-reference-label 显示在链接中# 之后的URL 中。所以必须使用漂亮的标签名称。此外，TOC 总是会创建一个指向Section to cross-reference 的#-链接，因此最终会有两个不同的#-链接指向同一部​​分。

如果你想给你的链接一个不同的名字，你总是可以使用:ref:`Link title <lmy-reference-label>`

【参考方案2】：

2016 年新的、更好的答案！

autosection extension 让您轻松做到这一点。

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


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

那么，以后……

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


A link-  :ref:`Internal Headline`

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

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

您唯一需要注意的是，现在您不能在整个文档集合中复制内部标题。 （值得。）

【讨论】：

自从我写了这个答案，我在实践中发现了这个方法的几个问题。首先，部分重命名是一个问题。其次，您经常有想要使用的短节标题，例如“了解更多”或“概述”，如果您这样做，则无法使用。解决方案：当/如果您重命名时添加部分标题；为短节标题添加节标题（如_page-title-learn-more）。这有点烦人，但我仍然喜欢主要依靠自动切片。

Sphinx 1.6 引入了autosectionlabel_prefix_document config option，它可以通过在每个部分标签前面加上它来自的文档的名称来避免重复的标题问题。

这是最好的解决方案。并且可以使用:ref:`Link title <Internal Headline>` 轻松修改链接标题。此外，您可以使用 :doc:`quickstart`

直接链接到页面（例如 quickstart.rst）

【参考方案3】：

例子：

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

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

这使用autosection feature，因此需要使用以下内容编辑config.py：

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

【讨论】：

在 2.0.0b1 中，他们添加了autosectionlabel_maxdepth，因此要使 autosectionlabel 起作用，您必须将该变量设置为 >=2。此外，如果将文档生成到子目录，例如html，则必须在 refs 前加上其名称：:ref:'html/Installation:Homebrew'。出于这个原因，您可能希望选择一些通用的目录名称，例如 generated，以使 ref 在与 HTML 以外的格式一起使用时看起来不那么奇怪。正因为如此，您不妨使用'Homebrew <Installation.html#Homebrew>'__ 来使用适当的 reST，而不是与 Sphinx 绑定。

我不需要html/ 前缀

【参考方案4】：

在 Sphinx 3.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

【讨论】：

这和top voted answer换角色一样。

@bad_coder 你所说的答案没有说明:any:

我怀疑您必须使用 :any: 因为您的目标声明中有 3 个点（应该是 2 个）。如果可以引用目标，则很可能是其他原因导致了问题。我尝试在Sphinx's github issue tracker 上搜索有关:any: 和:ref: 角色的错误报告，但似乎没有任何与此描述相匹配的内容。

【参考方案5】：

我一直在努力完成这项工作，我发现实际的符号是:ref:'dir-path/Installation:Homebrew'，其中dir-path 是到 config.py 所在位置的 Installation.rst 的相对路径

【参考方案6】：

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

章节标题必须在其前面加上文件名（此处为概述）：

overview.rst：

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

index.rst:

    :ref:`overview:API Overview`

但是，在引用链接时，文件名（此处为常量）不得存在：

常量.rst：

    .. _section-constants:

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

api.rst:

    :ref:`section-constants`

此外，要使其正常工作，必须启用扩展“autosectionlabel”：

conf.py:

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