斯芬克斯

Question

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

Answer 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时不要使用它：

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

RST，一般

将RST文件转换为HTML的工具不一定具有集合的概念。例如，如果您依赖github将RST文件转换为HTML，或者使用rst2html之类的命令行工具，就是这种情况。不幸的是，用于获得所需结果的各种方法取决于您使用的工具。例如，如果您使用rst2html并希望文件A.rst链接到文件other.rst中名为“Section”的部分，并且您希望最终的HTML在浏览器中工作，那么{ {1}}将包含：

A.rst

您必须链接到最终的HTML文件，您必须知道该部分的`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.是什么。如果你想对通过github提供的文件做同样的事情：

id

您也需要知道该部分的`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``.。但是，您链接到RST文件，因为它只在访问创建HTML的RST文件时。（在撰写本答案时，不允许直接访问HTML。）

有一个完整的示例here。

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

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

Answer 3

忽略此答案，它不起作用：更好地使用Louis的答案

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

.. _ShortAnchor:

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

Some text.

要引用该标题，请使用：

For more details, see ShortAnchor_.

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

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

See `Target Header goes here`_ chapter.

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

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

Answer 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

Answer 5

示例：

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

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

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

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

Answer 6

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

Answer 7

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

部分标题必须使用前面的文件名（此处概述）来引用：

概述.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"
    ]

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

7 个答案:

斯芬克斯

RST，一般