python-sphinx - 添加对另一个页面中的副标题或 anchor 的交叉引用

Question

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

Answer 1

“reST/Sphinx”这一表述使得问题的范围不清楚。是关于一般和 Sphinx 中的reStructuredText，还是仅关于在Sphinx 中使用的reStructuredText(而不是一般的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 时不要使用它:

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 将包含:

`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 。