Domain API

Domain(env: BuildEnvironment)

Ein Domain ist dazu gedacht, eine Gruppe von „Objekt“-Beschreibungsdirektiven für Objekte ähnlicher Art und entsprechende Rollen, um auf sie zu verweisen, zu bündeln. Beispiele hierfür sind Python-Module, Klassen, Funktionen usw., Elemente einer Vorlagensprache, Sphinx-Rollen und -Direktiven usw.

Jede Domain hat einen separaten Speicher für Informationen über vorhandene Objekte und wie auf sie in self.data verwiesen werden kann, was ein Wörterbuch sein muss. Sie muss auch mehrere Funktionen implementieren, die die Objektinformationen in einer domänenunabhängigen Weise für Teile von Sphinx bereitstellen, die es dem Benutzer ermöglichen, Objekte domänenunabhängig zu referenzieren oder zu suchen.

Zu self.data: Da alle Objekt- und Querverweisinformationen in einer BuildEnvironment-Instanz gespeichert sind, wird das Objekt domain.data auch im Wörterbuch env.domaindata unter dem Schlüssel domain.name gespeichert. Vor Beginn des Build-Prozesses wird jede aktive Domäne instanziiert und das Umgebungsobjekt übergeben; das domaindata-Wörterbuch muss dann entweder nicht vorhanden sein oder ein Wörterbuch sein, dessen Schlüssel „version“ mit dem Attribut data_version der Domänenklasse übereinstimmt. Andernfalls wird OSError ausgelöst und die serialisierte Umgebung verworfen.

add_object_type(name: str, objtype: ObjType) → None

Einen Objekttyp hinzufügen.

check_consistency() → None

Konsistenzprüfungen durchführen (experimentell).

clear_doc(docname: str) → None

Spuren eines Dokuments aus den domänenspezifischen Inventaren entfernen.

directive(name: str) → type[Directive] | None

Eine Direktiven-Adapterklasse zurückgeben, die der registrierten Direktive immer ihren vollständigen Namen („domain:name“) als self.name gibt.

get_enumerable_node_type(node: Node) → str | None

Typ von aufzählbaren Knoten abrufen (experimentell).

get_full_qualified_name(node: Element) → str | None

Vollqualifizierten Namen für den gegebenen Knoten zurückgeben.

get_objects() → Iterable[tuple[str, str, str, str, str, int]]

Ein iterierbares Objekt von „Objektbeschreibungen“ zurückgeben.

Objektbeschreibungen sind Tupel mit sechs Elementen

name

Vollqualifizierter Name.

Anzeigename

Name, der beim Suchen/Verknüpfen angezeigt werden soll.

Typ

Objekttyp, ein Schlüssel in self.object_types.

Dokumentenname

Das Dokument, in dem er zu finden ist.

Anker

Der Ankername für das Objekt.

Priorität

Wie „wichtig“ das Objekt ist (bestimmt die Platzierung in Suchergebnissen). Einer von

1

Standardpriorität (platziert vor Volltext-Übereinstimmungen).

0

Objekt ist wichtig (platziert vor Standardprioritätsobjekten).

2

Objekt ist unwichtig (platziert nach Volltext-Übereinstimmungen).

-1

Objekt sollte überhaupt nicht in der Suche angezeigt werden.

get_type_name(type: ObjType, primary: bool = False) → str

Vollständigen Namen für den gegebenen ObjType zurückgeben.

merge_domaindata(docnames: Set[str], otherdata: dict[str, Any]) → None

Daten bezüglich docnames aus einem anderen Domaindaten-Inventar zusammenführen (kommt von einem Subprozess bei parallelen Builds).

process_doc(env: BuildEnvironment, docname: str, document: nodes.document) → None

Ein Dokument verarbeiten, nachdem es von der Umgebung gelesen wurde.

process_field_xref(pnode: pending_xref) → None

Eine in einem Feld des Dokuments erstellte ausstehende Querverweisung verarbeiten. Zum Beispiel Informationen über den aktuellen Gültigkeitsbereich anhängen.

resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) → list[tuple[str, nodes.reference]]

Die ausstehende Querverweisung node mit dem gegebenen target auflösen.

Die Referenz stammt von einer „any“- oder ähnlichen Rolle, was bedeutet, dass wir den Typ nicht kennen. Andernfalls sind die Argumente dieselben wie für resolve_xref().

Die Methode muss eine Liste (potenziell leer) von Tupeln ‘domain:role‘, newnode zurückgeben, wobei ‘domain:role‘ der Name einer Rolle ist, die dieselbe Referenz erstellen könnte, z. B. ‘py:func‘. newnode ist das, was resolve_xref() zurückgeben würde.

Hinzugefügt in Version 1.3.

resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) → nodes.reference | None

Die ausstehende Querverweisung node mit dem gegebenen typ und target auflösen.

Diese Methode sollte einen neuen Knoten zurückgeben, um den xref-Knoten zu ersetzen, der den contnode enthält, der den Markup-Inhalt der Querverweisung darstellt.

Wenn keine Auflösung gefunden werden kann, kann None zurückgegeben werden; der xref-Knoten wird dann an das missing-reference-Ereignis weitergegeben und, wenn dies keine Auflösung ergibt, durch contnode ersetzt.

Die Methode kann auch sphinx.environment.NoUri auslösen, um zu unterdrücken, dass das missing-reference-Ereignis ausgelöst wird.

role(name: str) → RoleFunction | None

Eine Rollen-Adapterfunktion zurückgeben, die der registrierten Rolle immer ihren vollständigen Namen („domain:name“) als erstes Argument gibt.

setup() → None

Domänenobjekt einrichten.

dangling_warnings: ClassVar[dict[str, str]] = {}

Rollennamen -> eine Warnmeldung, wenn die Referenz fehlt

data: dict[str, Any]

Datenwert

data_version: ClassVar[int] = 0

Datenversion, erhöhen Sie diese, wenn sich das Format von self.data ändert

directives: ClassVar[dict[str, type[Directive]]] = {}

Direktivname -> Direktivenklasse

enumerable_nodes: ClassVar[dict[type[Node], tuple[str, TitleGetter | None]]] = {}

node_class -> (enum_node_type, title_getter)

indices: ClassVar[list[type[Index]]] = []

eine Liste von Index-Unterklassen

initial_data: ClassVar[dict[str, Any]] = {}

Datenwert für eine neue Umgebung

label: ClassVar[str] = ''

Domänenbezeichnung: länger, beschreibender (wird in Nachrichten verwendet)

name: ClassVar[str] = ''

Domänenname: sollte kurz, aber eindeutig sein

object_types: ClassVar[dict[str, ObjType]] = {}

Typ (normalerweise Direktive) Name -> ObjType-Instanz

roles: ClassVar[dict[str, RoleFunction | XRefRole]] = {}

Rollennamen -> Rollen-Callable

class sphinx.domains.ObjType(lname: str, /, *roles: Any, **attrs: Any)

Ein ObjType ist die Beschreibung für einen Objekttyp, den eine Domain dokumentieren kann. Im Attribut object_types von Domain-Unterklassen werden Objekttypnamen auf Instanzen dieser Klasse abgebildet.

Konstruktorargumente

• lname: lokalisierter Name des Typs (Domain-Name nicht enthalten)

• roles: alle Rollen, die auf ein Objekt dieses Typs verweisen können

• attrs: Objektattribute – derzeit ist nur „searchprio“ bekannt, das die Priorität des Objekts im Volltextsuchindex definiert, siehe Domain.get_objects().

class sphinx.domains.Index(domain: Domain)

Ein Index ist die Beschreibung für einen domänenspezifischen Index. Um einen Index zu einer Domain hinzuzufügen, erben Sie von Index und überschreiben die drei Namensattribute

• name ist ein Bezeichner, der zur Generierung von Dateinamen verwendet wird. Er wird auch als Hyperlinkziel für den Index verwendet. Daher können Benutzer die Indexseite über die Rolle ref und eine Zeichenkette, die Domain-Name und Attribut name kombiniert (z. B. :ref:`py-modindex`), referenzieren.

• localname ist der Abschnittstitel für den Index.

• shortname ist ein kurzer Name für den Index, der in der Relationsleiste in der HTML-Ausgabe verwendet wird. Kann leer sein, um Einträge in der Relationsleiste zu deaktivieren.

und Bereitstellen einer generate()-Methode. Fügen Sie dann die Indexklasse zur indices-Liste Ihrer Domain hinzu. Erweiterungen können Indizes zu bestehenden Domains über add_index_to_domain() hinzufügen.

Geändert in Version 3.0: Indexseiten können über die Rolle ref nach Domain- und Indexnamen referenziert werden.

abstractmethod generate(docnames: Iterable[str] | None = None) → tuple[list[tuple[str, list[IndexEntry]]], bool]

Einträge für den Index abrufen.

Wenn docnames angegeben ist, beschränkt sich die Suche auf Einträge, die auf diese Dokumentennamen verweisen.

Der Rückgabewert ist ein Tupel von (inhalt, kollabieren)

kollabieren

Ein Boolescher Wert, der bestimmt, ob Untereinträge zusammengeklappt werden sollen (für Ausgabeformate, die das Zusammenklappen von Untereinträgen unterstützen).

inhalt:

Eine Sequenz von (buchstabe, einträge)-Tupeln, wobei buchstabe die „Überschrift“ für die angegebenen einträge ist, normalerweise der Anfangsbuchstabe, und einträge eine Sequenz einzelner Einträge ist. Jeder Eintrag ist ein IndexEntry.

class sphinx.domains.IndexEntry(name: str, subtype: int, docname: str, anchor: str, extra: str, qualifier: str, descr: str)

Ein Indexeintrag.

Hinweis

Der *Qualifikator* und die *Beschreibung* werden für einige Ausgabeformate, wie z.B. LaTeX, nicht gerendert.

name: str

Der anzuzeigende Name des Indexeintrags.

subtype: int

Der verwandte Untereintrags-Typ. Einer von

0

Ein normaler Eintrag.

1

Ein Eintrag mit Untereinträgen.

2

Ein Untereintrag.

docname: str

Der *docname*, an dem sich der Eintrag befindet.

anchor: str

Anker für den Eintrag innerhalb von docname

extra: str

Zusatzinformationen für den Eintrag.

qualifier: str

Qualifikator für die Beschreibung.

descr: str

Beschreibung für den Eintrag.

class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Direktive zur Beschreibung einer Klasse, Funktion oder eines ähnlichen Objekts.

Nicht direkt verwendet, sondern abgeleitet (in domänenspezifischen Direktiven), um benutzerdefiniertes Verhalten hinzuzufügen.

_object_hierarchy_parts(sig_node: desc_signature) → tuple[str, ...]

Gibt ein Tupel von Zeichenketten zurück, einen Eintrag für jeden Teil der Objekt-Hierarchie (z. B. ('modul', 'submodul', 'Klasse', 'methode')). Das zurückgegebene Tupel wird verwendet, um Kinder in der Inhaltsübersicht richtig zu verschachteln, und kann auch in der Methode _toc_entry_name() verwendet werden.

Diese Methode darf nicht außerhalb der Generierung der Inhaltsübersicht verwendet werden.

_toc_entry_name(sig_node: desc_signature) → str

Gibt den Text des Eintrags der Inhaltsübersicht für das Objekt zurück.

Diese Funktion wird einmal in run() aufgerufen, um den Namen für den Eintrag der Inhaltsübersicht festzulegen (ein spezielles Attribut _toc_name wird auf dem Objektknoten gesetzt, das später in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() verwendet wird, wenn die Einträge der Inhaltsübersicht gesammelt werden).

Um Inhaltsübersichtseinträge für ihre Objekte zu unterstützen, müssen Domains diese Methode überschreiben und auch die Konfigurationseinstellung toc_object_entries_show_parents berücksichtigen. Domains müssen auch _object_hierarchy_parts() überschreiben, mit einem (Zeichenketten-)Eintrag für jeden Teil der Objekt-Hierarchie. Das Ergebnis dieser Methode wird auf dem Signaturknoten gesetzt und kann als sig_node['_toc_parts'] zugegriffen werden, um innerhalb dieser Methode verwendet zu werden. Das resultierende Tupel wird auch verwendet, um Kinder in der Inhaltsübersicht richtig zu verschachteln.

Eine beispielhafte Implementierung dieser Methode befindet sich in der Python-Domain (PyObject._toc_entry_name()). Die Python-Domain setzt das Attribut _toc_parts innerhalb der Methode handle_signature().

add_target_and_index(name: ObjDescT, sig: str, signode: desc_signature) → None

Fügt Querverweis-IDs und Einträge zu self.indexnode hinzu, falls zutreffend.

name ist alles, was handle_signature() zurückgegeben hat.

after_content() → None

Wird nach dem Parsen des Inhalts aufgerufen.

Wird verwendet, um Informationen über den aktuellen Direktivenkontext in der Build-Umgebung zurückzusetzen.

before_content() → None

Wird vor dem Parsen des Inhalts aufgerufen.

Wird verwendet, um Informationen über den aktuellen Direktivenkontext in der Build-Umgebung zu setzen.

get_signatures() → list[str]

Ruft die zu dokumentierenden Signaturen aus den Direktivenargumenten ab.

Standardmäßig werden Signaturen als Argumente übergeben, eine pro Zeile.

handle_signature(sig: str, signode: desc_signature) → ObjDescT

Parst die Signatur sig.

Die einzelnen Knoten werden dann an signode angehängt. Wenn ValueError ausgelöst wird, wird das Parsen abgebrochen und die gesamte sig in einen einzelnen desc_name-Knoten gestellt.

Der Rückgabewert sollte ein Wert sein, der das Objekt identifiziert. Er wird unverändert an add_target_and_index() übergeben und ansonsten nur zum Überspringen von Duplikaten verwendet.

run() → list[Node]

Haupt-Direktiven-Einstiegsfunktion, die von docutils beim Anwenden der Direktive aufgerufen wird.

Diese Direktive ist so konzipiert, dass sie recht einfach abgeleitet werden kann. Daher delegiert sie an mehrere zusätzliche Methoden. Was sie tut:

• Ermitteln, ob sie als domänenspezifische Direktive aufgerufen wird, setzen von self.domain

• Erstellen eines desc-Knotens, um die gesamte Beschreibung darin unterzubringen

• Parsen von Standardoptionen, derzeit no-index

• Erstellen eines Indexknotens, falls erforderlich, als self.indexnode

• Parsen aller übergebenen Signaturen (gemäß self.get_signatures()), wobei self.handle_signature() verwendet wird, das entweder einen Namen zurückgeben oder ValueError auslösen sollte

• Hinzufügen von Indexeinträgen mit self.add_target_and_index()

• Parsen des Inhalts und Behandeln von Feldern darin

transform_content(content_node: desc_content) → None

Kann verwendet werden, um den Inhalt zu manipulieren.

Aufgerufen nach der Erstellung des Inhalts durch verschachteltes Parsen, aber bevor das Ereignis object-description-transform ausgelöst wird und bevor die Info-Felder transformiert werden.

final_argument_whitespace = True

Kann das letzte Argument Leerzeichen enthalten?

has_content = True

Kann die Direktive Inhalt haben?

option_spec: ClassVar[OptionSpec] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}

Zuordnung von Optionsnamen zu Validierungsfunktionen.

optional_arguments = 0

Anzahl der optionalen Argumente nach den erforderlichen Argumenten.

required_arguments = 1

Anzahl der erforderlichen Direktivenargumente.

Python Domain

class sphinx.domains.python.PythonDomain(env: BuildEnvironment)

Python-Sprachdomain.

objects

modules

note_object(name: str, objtype: str, node_id: str, aliased: bool = False, location: Any = None) → None

Notiere ein Python-Objekt für Querverweise.

Hinzugefügt in Version 2.1.

note_module(name: str, node_id: str, synopsis: str, platform: str, deprecated: bool) → None

Notiere ein Python-Modul für Querverweise.

Hinzugefügt in Version 2.1.

Vorheriger

Docutils Markup API

Nächster

Parser API