`sphinx.ext.autosectionlabel` -- 通过标题引用章节¶

在 1.4 版本加入.

默认情况下，对章节的交叉引用使用标签（参见 ref）。作为替代，此扩展允许通过标题来引用章节。

例如：

A Plain Title
-------------

This is the text of the section.

It refers to the section title, see :ref:`A Plain Title`.

在构建过程中，此扩展为每个章节生成标签。若在整个文档中使用重复的章节名称，则默认情况下，任何一个节名称都将用于目标。如果一个标题名在文档的不同部分之间多次出现， autosectionlabel_prefix_document 配置变量可为它们生成不同的标签。

配置¶

autosectionlabel_prefix_document¶

如果为True，则在每个节标签前面加上它所在文档的名称，后跟冒号。例如对于文档中出现的、在 Introdution 部分的 index.rst，生成的标签名为 index:Introduction。当同名的章节标题出现在文档的不同部分中时，有助于避免造成歧义。

autosectionlabel_maxdepth¶

如果设置了该值， autosectionlabel 将根据章节的深度选择要标记的章节。例如，当 autosectionlabel_maxdepth 设置为 1 时，仅为顶级章节生成标签，而较深的章节则不生成标签。默认值为 None （即所有章节均生成标签）。

WARNING: undefined label 警告表示您在 ref 中的引用拼写错误。使用 -vvv （参见 -v ）调用 sphinx-build 将打印所有章节名称及其生成的标签。此输出有助于找到正确的引用标签。