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 内の参照がスペルミスであることを示します。sphinx-build を -vvv を付けて起動すると（(in Python v3.12)-v を参照）、すべてのセクション名とそれらに対して生成されたラベルが出力されます。この出力は、適切な参照ラベルを見つけるのに役立ちます。