我可以使用不同于章节标题的自定义章节 link 吗？

Question

我正在使用 reStructuredText 和 Sphinx 编写一些文档，但我以后可能想更改我的章节标题：

Some Title Which I May Want To Change
=====================================

对于这些章节标题，Sphinx 会生成一个 link，类似于 thepage#some-title-which-i-may-want-to-change。这意味着当我更改名称时，任何旧的 link 可能有人制作的现在都将被破坏。

我可以为与标题文本不同的标题使用自定义 link 吗？

.. use-this-link:: perma-title
Some Title Which I May Want To Change
=====================================

用link到thepage#perma-title。

Answer 1

Section headers generate an implicit hyperlink target based on the heading text. What you want is the ability to use a custom hyperlink target; an explicit hyperlink target。我们可以这样做：

.. _some-title-which-i-may-want-to-change:
.. _perma-title:

Some Title Which I May Want To Change
=====================================

这结合了一些功能来完成我们想要的：

• .. _perma-title: 向标题添加了明确的 hyperlink 目标。然而，如果没有这个，hyperlink 生成器 ¶ 仍将使用旧的隐式 hyperlink 目标。解决这个问题：
• .. _some-title-which-i-may-want-to-change: 是具有相同引用名称的显式 hyperlink 目标。文档指出这将“覆盖任何具有相同引用名称的隐式目标。”
• .. _some-title-which-i-may-want-to-change: 被定位为一个“链式”内部超 link 目标，给它一个去处。这意味着如果有人要访问 thepage#some-title-which-i-may-want-to-change，他们也会转到此标题。

通过这些更改，hyperlink 生成器符号 ¶ 将生成您想要的 thepage#perma-title link。