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¶
每个章节标签都应以所在文档的名称开头,并跟随一个冒号.例如,对于出现在文档
index.rst中名为Introduction的章节,其标签应为index:Introduction.这可以避免在不同文档中出现相同章节标题时产生歧义.
- autosectionlabel_maxdepth¶
如果设置,则 autosectionlabel 根据其深度选择用于标记的部分.例如,当将
autosectionlabel_maxdepth设置为 1 时,仅为顶级部分生成标签,而深层部分则不标记.默认值为None（禁用）.
调试¶
The WARNING: undefined label indicates that your reference in
ref is mis-spelled. Invoking sphinx-build with -vvv
(see -v) will print all section names and the labels that have been
generated for them. This output can help finding the right reference label.