Domains¶

Hinzugefügt in Version 1.0.

Ursprünglich wurde Sphinx für ein einziges Projekt konzipiert, die Dokumentation der Programmiersprache Python. Kurz darauf wurde es als Dokumentationstool für jedermann verfügbar gemacht, aber die Dokumentation von Python-Modulen blieb tief eingebettet – die grundlegendsten Direktiven, wie function, wurden für Python-Objekte entwickelt. Da Sphinx einigermaßen beliebt geworden ist, entwickelte sich Interesse daran, es für viele verschiedene Zwecke zu nutzen: C/C++-Projekte, JavaScript oder sogar reStructuredText-Markup (wie in dieser Dokumentation).

Während dies schon immer möglich war, ist es nun viel einfacher, die Dokumentation von Projekten zu unterstützen, die verschiedene Programmiersprachen verwenden, oder sogar solche, die von der Haupt-Sphinx-Distribution nicht unterstützt werden, indem für jeden solchen Zweck eine **Domain** bereitgestellt wird.

Eine Domain ist eine Sammlung von Markup (reStructuredText Direktiven und Rollen), um zusammengehörige Objekte zu beschreiben und darauf zu verlinken, z.B. Elemente einer Programmiersprache. Direktiven- und Rollennamen in einer Domain haben Namen wie domain:name, z.B. py:function. Domains können auch benutzerdefinierte Indizes bereitstellen (wie der Python-Modulindex).

Das Vorhandensein von Domains bedeutet, dass es keine Namensprobleme gibt, wenn ein Satz von Dokumentation auf z.B. C++ und Python-Klassen verweisen möchte. Es bedeutet auch, dass Erweiterungen, die die Dokumentation von völlig neuen Sprachen unterstützen, viel einfacher zu schreiben sind.

Dieser Abschnitt beschreibt, was die mit Sphinx ausgelieferten Domains bereitstellen. Die Domain-API ist ebenfalls dokumentiert, im Abschnitt Domain-API.

Eingebaute Domains¶

Die folgenden Domains sind in Sphinx enthalten

Drittanbieter-Domains¶

Mehrere Drittanbieter-Domains sind als Erweiterungen verfügbar, darunter

Andere Domains können im Python Package Index (über den Klassifikator Framework :: Sphinx :: Domain), auf GitHub oder GitLab gefunden werden.

Grundlegendes Markup¶

Die meisten Domains bieten eine Reihe von **Objektbeschreibungs-Direktiven**, die zur Beschreibung spezifischer Objekte verwendet werden, die von Modulen bereitgestellt werden. Jede Direktive benötigt eine oder mehrere Signaturen, um grundlegende Informationen über das Beschriebene zu liefern, und der Inhalt sollte die Beschreibung sein.

Eine Domain führt typischerweise ein internes Register aller Entitäten, um Querverweise zu ermöglichen. Typischerweise fügt sie auch Einträge im angezeigten allgemeinen Index hinzu. Wenn Sie das Hinzufügen eines Eintrags im angezeigten Index unterdrücken möchten, können Sie das Direktiven-Optionsflag :no-index-entry: verwenden. Wenn Sie die Objektbeschreibung aus dem Inhaltsverzeichnis ausschließen möchten, können Sie das Direktiven-Optionsflag :no-contents-entry: verwenden. Wenn Sie eine Objektbeschreibung typografisch setzen möchten, ohne sie überhaupt für Querverweise verfügbar zu machen, können Sie das Direktiven-Optionsflag :no-index: verwenden (was :no-index-entry: impliziert). Wenn Sie nichts typografisch setzen möchten, können Sie das Direktiven-Optionsflag :no-typesetting: verwenden. Dies kann beispielsweise verwendet werden, um nur ein Ziel und einen Indexeintrag für spätere Referenzen zu erstellen. Beachten Sie jedoch, dass nicht jede Direktive in jeder Domain diese Optionen unterstützt.

Hinzugefügt in Version 3.2: Die Direktiven-Option noindexentry in den Python-, C-, C++- und Javascript-Domains.

Hinzugefügt in Version 5.2.3: Die Direktiven-Option :nocontentsentry: in den Python-, C-, C++-, Javascript- und reStructuredText-Domains.

Hinzugefügt in Version 7.2: Die Direktiven-Option no-typesetting in den Python-, C-, C++-, Javascript- und reStructuredText-Domains.

Geändert in Version 7.2

Die Direktiven-Option :noindex: wurde in :no-index: umbenannt.
Die Direktiven-Option :noindexentry: wurde in :no-index-entry: umbenannt.
Die Direktiven-Option :nocontentsentry: wurde in :no-contents-entry: umbenannt.

Die vorherigen Namen bleiben als Aliase erhalten, werden aber in einer zukünftigen Version von Sphinx als veraltet markiert und entfernt.

Ein Beispiel für die Verwendung einer Python-Domain-Direktive

.. py:function:: spam(eggs)
                 ham(eggs)

   Spam or ham the foo.

Dies beschreibt die beiden Python-Funktionen spam und ham. (Beachten Sie, dass Sie Signaturen, die zu lang werden, aufteilen können, wenn Sie eine Backslash zu Zeilen hinzufügen, die in der nächsten Zeile fortgesetzt werden. Beispiel:

.. py:function:: filterwarnings(action, message='', category=Warning, \
                                module='', lineno=0, append=False)
   :no-index:

(Dieses Beispiel zeigt auch, wie das Flag :no-index: verwendet wird.)

Die Domains stellen auch Rollen bereit, die zurück zu diesen Objektbeschreibungen verlinken. Um beispielsweise auf eine der im obigen Beispiel beschriebenen Funktionen zu verlinken, könnten Sie sagen:

The function :py:func:`spam` does a similar thing.

Wie Sie sehen können, enthalten sowohl Direktiven- als auch Rollennamen den Domainnamen und den Direktivenamen.

Die Direktiven-Option :no-typesetting: kann verwendet werden, um ein Ziel (und einen Indexeintrag) zu erstellen, auf das später mit den von der Domain bereitgestellten Rollen verwiesen werden kann. Dies ist besonders nützlich für literales Programmieren.

.. py:function:: spam(eggs)
   :no-typesetting:

.. code:: python

   def spam(eggs):
       pass

The function :py:func:`spam` does nothing.

Standard-Domain

Für Dokumentationen, die Objekte nur aus einer einzigen Domain beschreiben, müssen Autoren den Namen bei jeder Direktive, Rolle usw. nicht erneut angeben, nachdem eine Standard-Domain festgelegt wurde. Dies kann entweder über den Konfigurationswert primary_domain oder über diese Direktive erfolgen:

.. default-domain:: name¶: Wählt eine neue Standard-Domain aus. Während primary_domain eine globale Standard-Domain festlegt, hat diese hier nur innerhalb desselben Fileswirkung.

Wenn keine andere Standard-Domain ausgewählt ist, ist die Python-Domain (benannt py) die Standard-Domain, hauptsächlich aus Kompatibilitätsgründen mit für ältere Versionen von Sphinx geschriebenen Dokumentationen.

Direktiven und Rollen, die zur Standard-Domain gehören, können ohne Angabe des Domainnamens erwähnt werden, d.h.

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

Syntax für Querverweise¶

Für von Domains bereitgestellte Querverweis-Rollen gelten dieselben Querverweis-Modifikatoren wie für allgemeine Querverweise. Kurz gesagt:

Sie können einen expliziten Titel und ein explizites Verweisziel angeben: :py:mod:`mathematical functions <math>` verweist auf das Modul math, aber der Linktext ist "mathematical functions".
Wenn Sie dem Inhalt ein Ausrufezeichen (!) voranstellen, wird keine Referenz/Hyperlink erstellt.
Wenn Sie dem Inhalt ein ~ voranstellen, ist der Linktext nur die letzte Komponente des Ziels. Zum Beispiel verweist :py:meth:`~queue.Queue.get` auf queue.Queue.get, zeigt aber nur get als Linktext an.