在另一个页面中添加对副标题或锚点的交叉引用 [英] Adding a cross-reference to a subheading or anchor in another page

问题描述

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

How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?

推荐答案

表达reST/Sphinx"使问题的范围变得不清楚.是关于一般和Sphinx的reStructuredText，还是仅关于Sphinx中使用的reStructuredText(而不是一般的reStructuredText)?我将涵盖这两种情况，因为使用 RST 的人可能会在某些时候遇到这两种情况:

The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:

除了可用于链接到各种实体(如类 (:class:))的特定域指令之外，还有通用的 :ref: 指令，记录在 此处.他们举了这个例子:

Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:

    .. _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 时使用它:

Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:

建议使用 ref 而非标准的 reStructuredText 链接到部分(如 Section title_)，因为它可以跨文件、更改部分标题以及支持交叉引用的所有构建器.

Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.

RST，一般情况

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

RST, in General

The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:

`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 提供的文件执行相同操作:

You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through 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 too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)

此处提供了完整示例.

这篇关于在另一个页面中添加对副标题或锚点的交叉引用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！