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

表达式“ reST / Sphinx”使问题的范围不清楚。它与一般和 Sphinx中的reStructuredText有关，还是仅与 Sphinx中所使用的 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时使用它：

建议使用ref而不是标准的reStructuredText链接到节（例如Section title_），因为它可以跨文件运行，更改节标题时以及支持交叉引用的所有构建器。

RST，一般

将RST文件转换为HTML的工具不一定具有集合的概念。例如，如果您依靠github将RST文件转换为HTML，或者使用诸如的命令行工具，就是这种情况rst2html。不幸的是，用于获得理想结果的各种方法因所使用的工具而异。例如，如果您使用rst2html并且希望文件A.rst链接到文件中名为“ Section”的部分，other.rst并且您希望最终的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！

该autosection扩展可以让你轻松做到这一点。

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


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

然后，以后...

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


A link-  :ref:`Internal Headline`

此扩展是内置的，因此您只需编辑 conf.py

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

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

例：

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

Homebrew另一个名为的文档中的节在哪里Installation.rst？

这使用了自动切片功能，因此需要config.py使用以下内容进行编辑：

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