`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，则在每个章节标签前面加上它所在的文档名称，后面跟一个冒号。例如，index:Introduction 表示出现在 index.rst 文档中的名为 Introduction 的章节。在不同文档中出现相同的章节标题时，这有助于避免歧义。

autosectionlabel_maxdepth¶: 如果设置，autosectionlabel 会根据其深度选择要标记的章节。例如，当将 autosectionlabel_maxdepth 设置为 1 时，只会为顶级章节生成标签，而更深层的章节不会被标记。默认值为 None（已禁用）。

调试¶

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