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

Added in version 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¶

为每个章节标签添加所在文档的名称，后跟一个冒号。例如，对于名为 Introduction 的章节，它出现在文档 index.rst 中，标签为 index:Introduction。当相同的章节标题出现在不同文档中时，有助于避免歧义。

autosectionlabel_maxdepth¶

如果设置了，autosectionlabel 通过其深度选择要标记的章节。例如，当 autosectionlabel_maxdepth 设置为 1 时，仅为顶级章节生成标签，而深层章节不会被标记。默认为 None （即所有章节都被标记）。

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