如何在不创建任意标签的情况下在sphinx restructuredtext中创建标题的内部链接？

Question

我有一份包含许多标题和小标题的文件.进一步在文本中我想链接回其中一个标题.如果没有:ref:标签的冗余,我怎么能这样做？内容似乎拿起标题就好了.我希望得到这样的东西:`#polled-data-retrieval`_.

Answer 1

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>

Answer 2

2016年新的,更好的答案!

自动分割扩展允许您使用真实的交叉引用轻松完成此操作.

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


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

然后,以后......

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


A link-  :ref:`Internal Headline`

此扩展程序是内置的,因此您只需编辑即可 conf.py

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

您唯一需要注意的是,现在您无法在整个文档集合中复制内部标题.(值得.)

Answer 3

克里斯回答中的一小部分内容：

如果要链接到标题而不使用链接标题的确切名称，则可以这样进行：

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>

Answer 4

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

建议使用 ref 而不是指向部分（如`Section title`_）的标准 reStructuredText 链接，因为它可以跨文件工作，当部分标题更改时，如果不正确，将发出警告，并且适用于所有支持交叉引用的构建器。
来源：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`引用的对象。

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