sphinx.ext.autosectionlabel – Ermöglicht das Referenzieren von Abschnitten anhand ihrer Titel

Hinzugefügt in Version 1.4.

Standardmäßig verwenden Querverweise auf Abschnitte Labels (siehe ref). Diese Erweiterung ermöglicht es Ihnen, stattdessen Abschnitte anhand ihrer Titel zu referenzieren.

Zum Beispiel

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

This is the text of the section.

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

Intern generiert diese Erweiterung die Labels für jeden Abschnitt. Wenn im gesamten Dokument gleiche Abschnittsnamen verwendet werden, wird standardmäßig eines davon als Ziel verwendet. Die Konfigurationsvariable autosectionlabel_prefix_document kann verwendet werden, um mehrfach, aber in verschiedenen Dokumenten vorkommende Überschriften eindeutig zu machen.

Konfiguration

autosectionlabel_prefix_document
Typ:
bool
Standard:
False

True, um jedes Abschnittslabel mit dem Namen des Dokuments, in dem es sich befindet, gefolgt von einem Doppelpunkt zu versehen. Zum Beispiel index:Introduction für einen Abschnitt namens Introduction, der im Dokument index.rst vorkommt. Nützlich, um Mehrdeutigkeiten zu vermeiden, wenn dieselbe Abschnittsüberschrift in verschiedenen Dokumenten vorkommt.

autosectionlabel_maxdepth
Typ:
int | None
Standard:
None

Wenn gesetzt, wählt autosectionlabel die Abschnitte für die Beschriftung nach ihrer Tiefe aus. Wenn zum Beispiel 1 auf autosectionlabel_maxdepth gesetzt ist, werden nur für Abschnitte der obersten Ebene Labels generiert, und tiefere Abschnitte werden nicht beschriftet. Der Standardwert ist None (d.h. alle Abschnitte werden beschriftet).

Fehlersuche

Die Meldung WARNING: undefined label zeigt an, dass Ihr Verweis in ref falsch geschrieben ist. Wenn Sie sphinx-build mit -vvv aufrufen (siehe -v), werden alle Abschnittsnamen und die für sie generierten Labels ausgegeben. Diese Ausgabe kann helfen, das richtige Referenzlabel zu finden.