Auf dieser Seite

Guidedog / Dokumentation 0.2.0

Objekttypen deklarieren

Ein Projekt kann Namen außerhalb der Standarddomänen brauchen. Deklarieren Sie deren Objekttypen in TOML. Guidedog erzeugt dann Ziele, Indexeinträge und Rollen ohne Python-Erweiterung. Die Deklaration beschreibt Syntax, kein ausführbares Verhalten.

Ziele: add_crossref_type

[[crossref_types]]
directive = "setting"
role = "setting"
index = "pair: %s; setting"

.. setting:: DEBUG erzeugt ein Ziel mit ID setting-DEBUG und einen Indexeintrag; :setting:`DEBUG` verlinkt es wie bei Sphinx. index entspricht Sphinx' indextemplate: der Typ (single, pair, triple, see, seealso) steht vor dem ersten Doppelpunkt, danach der Eintrag mit %s als Name.

Beschreibungen: add_object_type

[[object_types]]
directive = "django-admin"
role = "djadmin"
index = "pair: %s; django-admin command"
name = "first-word"
display = "django-admin %s"
program = true

.. django-admin:: migrate [app_label] beschreibt den Befehl wie jedes Objekt: Signatur, Inhalt, ID (django-admin-migrate) und Indexeintrag. In Sphinx kann parse_node die Signatur lesen; typische Aufgaben werden hier mit Feldern festgelegt:

name

"whole" (Vorgabe): der Name ist die ganze Signatur. "first-word": der Name reicht bis zum ersten Leerzeichen; b(reak) [lineno] von pdb heißt etwa b(reak).

display

Die Darstellung der Signatur, vertreten durch %s. Vorgabe ist die ursprüngliche Schreibweise.

program

true: Der Name wird zum Programm für nachfolgende Optionen, wie bei .. program::.

Weitere Namen für Direktiven

Eine Erweiterung kann Sphinx-Direktiven unter anderem Namen registrieren:

[directive_aliases]
django-admin-option = "option"
awaitablefunction = "py:function"

Ein Ziel ohne Domäne bezeichnet eine Standarddirektive oder eine der Standarddomäne. py:function nennt seine Domäne ausdrücklich.

Migration

guidedog migrate findet die in conf.py genannten Erweiterungen, die Projektmodule sind. Es liest ihre Aufrufe von add_crossref_type, add_object_type und add_directive ohne Ausführung und schreibt die Tabellen. Nicht deklarierbare parse_node-Funktionen (mit name, display und program nachbilden) sowie Python-Direktiven, Rollen und Ereignishandler werden gemeldet.