`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.rst 中名為 Introduction 的章節會變成 index:Introduction。當相同的章節標題出現在不同的文件中時，這對於避免歧義很有用。

autosectionlabel_maxdepth¶

如果設定，autosectionlabel 會依其深度選擇要標記的章節。例如，當 autosectionlabel_maxdepth 設定為 1 時，只會為頂層章節產生標籤，而更深層的章節則不會標記。預設值為 None（即所有章節都會被標記）。

WARNING: undefined label 表示您在 ref 中的參考拼寫錯誤。使用 -vvv 呼叫 sphinx-build（請參閱 -v）將印出所有章節名稱和為其產生的標籤。此輸出可以幫助找到正確的參考標籤。