sphinx.ext.autosectionlabel – 允许引用 section 使用其标题

1.4 新版功能.

这个插件允许您引用它的 section 标题。这将影响到引用角色（ref）。

例如

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

This is the text of the section.

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

在内部，这个插件生成每个 section 的标签。如果在整个文档中使用相同的 section 名，则默认情况下目标使用任意一个 section 名。配置变量 autosectionlabel_prefix_document 可以用来使标题出现多次但在不同的文档中是唯一的。

配置

autosectionlabel_prefix_document

True 表示在每个 section 标签前加上它所在文档的名称，然后加上冒号。例如，在 index:Introduction 文档中，名为 Introduction 的章节的索引 index:Introduction。当同一 section 标题出现在不同的文档中时，这有助于避免歧义。

autosectionlabel_maxdepth

如果设置了，autosectionlabel 根据深度选择要标记的部分。例如，当设置 autosectionlabel_maxdepth 为 1 时，标签只会为顶级部分生成，深层部分不被标记。它默认为 None （禁用）。