sphinx.ext.autosectionlabel -- Allow referencing sections by their title

Added in version 1.4.

By default, cross-references to sections use labels (see ref). This extension allows you to instead refer to sections by their title.

例えば:

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
Type:
bool
Default:
False

Trueを設定すると、各セクションのラベルの前に、そのセクションが含まれている文書の名前とコロンが付きます。たとえば、文書 index.rst に表示される Introduction というセクションの index:Introduction です。異なる文書に同じセクション見出しが表示される場合に曖昧さを避けるのに役立ちます。

autosectionlabel_maxdepth
Type:
int | None
Default:
None

If set, autosectionlabel chooses the sections for labeling by its depth. For example, when set 1 to autosectionlabel_maxdepth, labels are generated only for top level sections, and deeper sections are not labeled. It defaults to None (i.e. all sections are labeled).

Debugging

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.