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.