35

我有一个包含许多标题和子标题的文档。在文本的后面，我想链接回其中一个标题。:ref:在没有标签冗余的情况下如何做到这一点？内容似乎很好地选择了标题。我希望有这样的事情：`#polled-data-retrieval`_。

4

4 回答 4

40

reStructuredText 支持隐式超链接目标。从reStructuredText 快速参考：

章节标题、脚注和引文会自动生成超链接目标（标题文本或脚注/引文标签用作超链接名称）。

所以以下文本（从 reStructuredText 快速参考、拼写错误和所有内容中提取）：

Titles are targets, too
=======================
Implict references, like `Titles are targets, too`_.

生成类似于以下内容的 HTML：

<strong><a name="title">Titles are targets, too</a></strong>

<p>Implict references, like <a href="#title">Titles are targets, too</a>.</p>
于 2013-09-09T18:35:07.620 回答
27

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-12-12T18:43:10.483 回答
23

克里斯回答的一个小补充：

如果您想链接到标题而不使用该链接的标题的确切名称，您可以这样做：

Titles are targets, too
=======================

See `here <#titles-are-targets-too>`_

这将呈现为：

<h1 id="titles-are-targets-too">Titles are targets, too</h1>

<p>See <a href="#titles-are-targets-too">here</a></p>
于 2018-10-12T09:06:00.500 回答
10

使用标题文本不是一个好的选择。标题可能会改变或可能会得到纠正。现在有一种简单的方法可以确定更改后链接断开的数量和位置。

建议在标准的 reStructuredText 链接上使用 ref 到节（如`Section title`_），因为它可以跨文件工作，当节标题更改时，如果不正确会发出警告，并且适用于支持交叉引用的所有构建器。
来源：https ://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref

使用Adam Michael Wood提出的sphinx.ext.autosectionlabel扩展至少是一种更结构化的方法，然后使用Chris提出的隐式定义的锚点。

您应该使用带有引用和符号目标名称的显式链接（就像 LaTeX 自古以来所做的那样。）

  1. 用于.. _refname:创建目标。
  2. 用于:ref:`refname`引用目标。

如果目标后面有标题，则此标题将用作链接文本。

于 2019-12-28T17:09:44.000 回答