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

Ajouté dans la 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.

Pas exemple:

A Plain Title
-------------

This is the text of the section.

It refers to the section title, see :ref:`A Plain Title`.

En interne, cette extension génère les étiquettes pour chaque section. Si les mêmes noms de section sont utilisés dans l’ensemble du document, l’un d’entre eux est utilisé comme cible par défaut. La variable de configuration autosectionlabel_prefix_document peut être utilisée pour rendre uniques les titres apparaissant plusieurs fois mais dans différents documents.

Configuration

autosectionlabel_prefix_document
Type:
bool
Défaut:
False

Vrai pour préfixer chaque étiquette de section avec le nom du document qui la contient, suivi de « deux points ». Par exemple, index:Introduction pour une section appelée Introduction qui apparaît dans un document index.rst. Utile pour éviter une ambiguïté quand le même titre de section apparaît dans différents documents.

autosectionlabel_maxdepth
Type:
int | None
Défaut:
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).

Débogage

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.