Querverweise¶

Eines der nützlichsten Merkmale von Sphinx ist die automatische Erstellung von Querverweisen durch semantische Rollen für Querverweise. Ein Querverweis auf eine Objektbeschreibung, wie z. B. :func:`spam`, erstellt einen Link zu der Stelle, an der spam() dokumentiert ist, und zwar passend für jedes Ausgabeformat (HTML, PDF, ePUB usw.).

Syntax¶

Sphinx unterstützt verschiedene Rollen für Querverweise, um Links zu anderen Elementen in der Dokumentation zu erstellen. Im Allgemeinen erstellt das Schreiben von :rolle:`ziel` einen Link zu dem Objekt mit dem Namen *ziel* des durch *rolle* angegebenen Typs. Der Linktext hängt von der Rolle ab, ist aber oft gleich oder ähnlich wie *ziel*.

Das Verhalten kann auf folgende Weise modifiziert werden:

Benutzerdefinierter Linktext: Sie können den Linktext explizit angeben, indem Sie die gleiche Notation wie bei reStructuredText externen Links verwenden: :rolle:`benutzerdefinierter Text <ziel>` verweist auf *ziel* und zeigt *benutzerdefinierter Text* als Linktext an.
Unterdrückter Link: Ein Ausrufezeichen (!) voranzustellen, verhindert die Erstellung eines Links, behält aber die visuelle Ausgabe der Rolle bei.

Zum Beispiel zeigt das Schreiben von :py:func:`!ziel`` ziel() an, ohne dass ein Link generiert wird.

Dies ist hilfreich in Fällen, in denen das Linkziel nicht existiert; z. B. Changelog-Einträge, die entfernte Funktionalität beschreiben, oder Drittanbieterbibliotheken, die intersphinx nicht unterstützen. Das Unterdrücken des Links verhindert Warnungen im nitpicky-Modus.
Modifizierter Domänenverweis: Beim Verweisen auf Domänenobjekte verkürzt ein Tilde (~) vorangestellt den Linktext auf die letzte Komponente des Ziels. Zum Beispiel verweist :py:meth:`~queue.Queue.get`` auf queue.Queue.get, zeigt aber nur get als Linktext an.

In der HTML-Ausgabe ist das title-Attribut des Links (das z. B. als Tooltip beim Überfahren mit der Maus angezeigt wird) immer der vollständige Zielname.

Objekte querverweisen¶

Diese Rollen werden mit ihren jeweiligen Domänen beschrieben.

Beliebige Speicherorte querverweisen¶

:ref:¶

Um Querverweise auf beliebige Speicherorte in beliebigen Dokumenten zu ermöglichen, werden die Standard-reStructuredText-Labels verwendet. Damit dies funktioniert, müssen die Labelnamen in der gesamten Dokumentation eindeutig sein. Es gibt zwei Möglichkeiten, auf Labels zu verweisen:

Wenn Sie ein Label direkt vor einem Abschnittstitel platzieren, können Sie darauf mit :ref:`label-name` verweisen. Zum Beispiel:
```
.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.
```
Die Rolle :ref: würde dann einen Link zum Abschnitt generieren, wobei der Linktitel „Section to cross-reference“ wäre. Dies funktioniert ebenso gut, wenn sich Abschnitt und Referenz in verschiedenen Quelldateien befinden.

Automatische Labels funktionieren auch mit Abbildungen. Zum Beispiel:
```
.. _my-figure:

.. figure:: whatever

   Figure caption
```
In diesem Fall würde ein Verweis :ref:`my-figure`` eine Referenz auf die Abbildung mit dem Linktext „Figure caption“ einfügen.

Das Gleiche gilt für Tabellen, denen mit der table-Direktive explizit eine Beschriftung gegeben wurde.
Labels, die nicht vor einem Abschnittstitel platziert sind, können dennoch referenziert werden, aber Sie müssen dem Link einen expliziten Titel geben, indem Sie diese Syntax verwenden: :ref:`Link title <label-name>`.

Hinweis

Referenzlabels müssen mit einem Unterstrich beginnen. Beim Referenzieren eines Labels muss der Unterstrich weggelassen werden (siehe Beispiele oben).

Die Verwendung von ref wird gegenüber Standard-reStructuredText-Links zu Abschnitten (wie `Section title`_) bevorzugt, da es dateiübergreifend funktioniert, bei geänderten Abschnittsüberschriften Warnungen auslöst und für alle Builder funktioniert, die Querverweise unterstützen.

Dokumente querverweisen¶

Hinzugefügt in Version 0.6.

Es gibt auch eine Möglichkeit, direkt auf Dokumente zu verlinken.

:doc:¶

Link zum angegebenen Dokument; der Dokumentenname kann ein relativer oder absoluter Pfad sein und ist immer case-sensitiv, auch unter Windows. Wenn beispielsweise der Verweis :doc:`parrot`` im Dokument sketches/index vorkommt, bezieht sich der Link auf sketches/parrot. Wenn der Verweis :doc:`/people`` oder :doc:`../people`` lautet, bezieht sich der Link auf people.

Wenn kein expliziter Linktext angegeben ist (wie üblich: :doc:`Monty Python members </people>`), ist die Linkunterschrift der Titel des angegebenen Dokuments.

Herunterladbare Dateien referenzieren¶

Hinzugefügt in Version 0.6.

:download:¶

Diese Rolle ermöglicht es Ihnen, Dateien in Ihrem Quellverzeichnis zu verknüpfen, die keine reStructuredText-Dokumente zum Anzeigen sind, sondern herunterladbare Dateien.

Wenn Sie diese Rolle verwenden, wird die referenzierte Datei automatisch zur Aufnahme in die Ausgabe markiert (offensichtlich nur für die HTML-Ausgabe). Alle herunterladbaren Dateien werden in ein Unterverzeichnis _downloads/<eindeutiger Hash>/ des Ausgabeverzeichnisses gelegt; doppelte Dateinamen werden behandelt.

Ein Beispiel

See :download:`this example script <../example.py>`.

Der angegebene Dateiname ist normalerweise relativ zum Verzeichnis, in dem sich die aktuelle Quelldatei befindet. Wenn er jedoch absolut ist (beginnend mit /), wird er als relativ zum obersten Quellverzeichnis behandelt.

Die Datei example.py wird in das Ausgabeverzeichnis kopiert und ein geeigneter Link dazu generiert.

Um nicht verfügbare Download-Links nicht anzuzeigen, sollten Sie ganze Absätze, die diese Rolle enthalten, umschließen.

.. only:: builder_html

   See :download:`this example script <../example.py>`.

Abbildungen nach Abbildungsnummer querverweisen¶

Hinzugefügt in Version 1.3.

Geändert in Version 1.5: Die Rolle numref kann auch auf Abschnitte verweisen. Und numref erlaubt {name} für den Linktext.

:numref:¶

Link zu den angegebenen Abbildungen, Tabellen, Code-Blöcken und Abschnitten; die Standard-reStructuredText-Labels werden verwendet. Wenn Sie diese Rolle verwenden, fügt sie eine Referenz auf die Abbildung mit dem Linktext ihrer Abbildungsnummer ein, z. B. „Abb. 1.1“.

Wenn ein expliziter Linktext angegeben ist (wie üblich: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), dient die Linkunterschrift als Titel der Referenz. Als Platzhalter werden %s und {number} durch die Abbildungsnummer und {name} durch die Abbildungsunterschrift ersetzt. Wenn kein expliziter Linktext angegeben ist, wird die Einstellung numfig_format als Fallback-Standard verwendet.

Wenn numfig False ist, werden Abbildungen nicht nummeriert, sodass diese Rolle keine Referenz, sondern das Label oder den Linktext einfügt.

Andere interessante Elemente querverweisen¶

Die folgenden Rollen erstellen möglicherweise einen Querverweis, beziehen sich aber nicht auf Objekte.

:confval:¶: Ein Konfigurationswert oder eine Einstellung. Indexeinträge werden generiert. Erstellt auch einen Link zur passenden confval-Direktive, falls vorhanden.

:envvar:¶: Eine Umgebungsvariable. Indexeinträge werden generiert. Erstellt auch einen Link zur passenden envvar-Direktive, falls vorhanden.

:token:¶: Der Name eines Grammatik-Tokens (wird verwendet, um Links zwischen productionlist-Direktiven zu erstellen).

:keyword:¶: Der Name eines Schlüsselworts in Python. Dies erstellt einen Link zu einem Referenzlabel mit diesem Namen, falls vorhanden.

:option:¶: Eine Befehlszeilenoption für ein ausführbares Programm. Dies generiert einen Link zu einer option-Direktive, falls vorhanden.

Die folgende Rolle erstellt einen Querverweis zu einem Begriff in einem Glossar.

:term:¶

Verweis auf einen Begriff in einem Glossar. Ein Glossar wird mit der glossary-Direktive erstellt, die eine Definitionsliste mit Begriffen und Definitionen enthält. Es muss sich nicht in derselben Datei wie die term-Markierung befinden; zum Beispiel haben die Python-Docs ein globales Glossar in der Datei glossary.rst.

Wenn Sie einen Begriff verwenden, der nicht in einem Glossar erklärt ist, erhalten Sie während des Builds eine Warnung.

Diese Rolle unterstützt auch benutzerdefinierten Linktext aus der allgemeinen Querverweissyntax.

Alles querverweisen¶

:any:¶

Hinzugefügt in Version 1.3.

Diese Komfortrolle versucht ihr Bestes, um ein gültiges Ziel für ihren Referenztext zu finden.

Zuerst versucht sie, Standard-Querverweise auf Ziele zu finden, die von doc, ref oder option referenziert würden.

Benutzerdefinierte Objekte, die durch Erweiterungen zur Standarddomäne hinzugefügt werden (siehe Sphinx.add_object_type()), werden ebenfalls durchsucht.
Dann sucht sie nach Objekten (Zielen) in allen geladenen Domänen. Es liegt an den Domänen, wie spezifisch eine Übereinstimmung sein muss. In der Python-Domäne würde beispielsweise ein Verweis auf :any:`Builder`` mit der Klasse sphinx.builders.Builder übereinstimmen.

Wenn keine oder mehrere Ziele gefunden werden, wird eine Warnung ausgegeben. Bei mehreren Zielen können Sie „any“ durch eine spezifische Rolle ersetzen.

Diese Rolle ist ein guter Kandidat für die Einstellung von default_role. Wenn Sie dies tun, können Sie Querverweise ohne viel Markup-Aufwand schreiben. Zum Beispiel in dieser Python-Funktionsdokumentation:

.. function:: install()

   This function installs a `handler` for every signal known by the
   `signal` module.  See the section `about-signals` for more information.

könnten Verweise auf einen Glossarbegriff (normalerweise :term:`handler`), ein Python-Modul (normalerweise :py:mod:`signal` oder :mod:`signal`) und einen Abschnitt (normalerweise :ref:`about-signals``) vorhanden sein.

Die Rolle any funktioniert auch zusammen mit der Erweiterung intersphinx: Wenn kein lokaler Querverweis gefunden wird, werden auch alle Objekttypen von Intersphinx-Inventaren durchsucht.