136

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

4

6 回答 6

237

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

建议在标准 reStructuredText 链接到节（如Section title_）上使用 ref，因为它适用于文件、节标题更改时以及支持交叉引用的所有构建器。

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

此处提供了一个完整的示例。

于 2013-10-23T13:51:13.537 回答
64

2016 年新的、更好的答案！

autosection扩展使您可以轻松地做到这一点。

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


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

那么，后来……

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


A link-  :ref:`Internal Headline`

这个扩展是内置的，所以你只需要编辑conf.py

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

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

于 2016-10-24T18:44:23.203 回答
15

例子：

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

whereHomebrew是另一个名为Installation.rst.

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

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
于 2019-02-23T16:30:55.897 回答
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
于 2020-10-13T10:02:54.620 回答
0

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

章节标题必须在其前面使用文件名（此处为概述）引用：

概述.rst：

    ************
    API Overview
    ************

索引.rst：

    :ref:`overview:API Overview`

但是，在引用链接时，文件名（此处为常量）不得存在：

常量.rst：

    .. _section-constants:

    *******************
    Enums and Constants
    *******************

api.rst：

    :ref:`section-constants`

此外，为此，必须启用扩展“autosectionlabel”：

配置文件：

    extensions = [
        ...
        "sphinx.ext.autosectionlabel"
    ]
于 2021-05-03T16:05:58.580 回答
0

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

于 2021-02-09T07:21:05.010 回答