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はその深さでラベル付けするセクションを選択します。たとえば、1を
autosectionlabel_maxdepth
に設定すると、ラベルはトップレベルのセクションに対してのみ生成され、それより深いセクションにはラベルが付けられません。デフォルトはNone
(無効)です。
Debugging¶
The WARNING: undefined label
indicates that your reference in
ref
is mis-spelled. Invoking sphinx-build with -vv
(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.