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

Question

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

Answer 1

忽略这个答案，它不起作用：更好地使用下面的the answer from Louis

对于锚点，您可以定义“短”锚点名称，如下所示：

.. _ShortAnchor:

Target Header goes here
=======================

Some text.

要引用该标题，请使用：

For more details, see ShortAnchor_.

请注意，这甚至会将ShortAnchor扩展为标题的全名。

您也可以使用完整的标题名称，如：

See `Target Header goes here`_ chapter.

但是这更容易修改标题文本。

所有这些都适用于多个源文件，这些文件是最终文档的一部分。

Answer 2

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

Sphinx

除了可用于链接到各种实体（如类（: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时不要使用它：

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

RST, in General

将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文件，因为它只在访问创建HTML的RST文件时。 （在撰写本答案时，不允许直接访问HTML。）

一个完整的例子是here。

Answer 3

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',
]

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

Answer 4

例：

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

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

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

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