sphinx.ext.viewcode – Links zum hervorgehobenen Quellcode hinzufügen

Modulautor: Georg Brandl

Hinzugefügt in Version 1.0.

Diese Erweiterung betrachtet Ihre Python-Objektbeschreibungen (.. class::, .. function:: usw.) und versucht, die Quelldateien zu finden, in denen die Objekte enthalten sind. Wenn gefunden, wird für jedes Modul eine separate HTML-Seite mit einer hervorgehobenen Version des Quellcodes ausgegeben und zu allen Objektbeschreibungen ein Link hinzugefügt, der zum Quellcode des beschriebenen Objekts führt. Ein Link vom Quellcode zurück zur Beschreibung wird ebenfalls eingefügt.

Warnung

Grundsätzlich importiert die viewcode-Erweiterung die zu verlinkenden Module. Wenn Module beim Import Nebeneffekte haben, werden diese beim Ausführen von sphinx-build ausgeführt.

Wenn Sie Skripte (im Gegensatz zu Bibliotheksmodulen) dokumentieren, stellen Sie sicher, dass ihre Hauptroutine durch eine if __name__ == '__main__'-Bedingung geschützt ist.

Zusätzlich können Sie, wenn Sie die Module nicht von viewcode importieren lassen möchten, den Speicherort des Quellcodes mithilfe des viewcode-find-source-Ereignisses an viewcode mitteilen.

Wenn viewcode_follow_imported_members aktiviert ist, müssen Sie importierte Attribute auch über das Ereignis viewcode-follow-imported auflösen.

Diese Erweiterung funktioniert nur für HTML-bezogene Builder wie html, applehelp, devhelp, htmlhelp, qthelp und so weiter, außer singlehtml. Standardmäßig unterstützt der epub-Builder diese Erweiterung nicht (siehe viewcode_enable_epub).

Konfiguration

viewcode_follow_imported_members
Typ:
bool
Standard:
True

Wenn dies True ist, gibt die viewcode-Erweiterung das Ereignis viewcode-follow-imported aus, um den Modulnamen von anderen Erweiterungen auflösen zu lassen.

Hinzugefügt in Version 1.3.

Geändert in Version 1.8: Umbenannt von viewcode_import in viewcode_follow_imported_members.

viewcode_enable_epub
Typ:
bool
Standard:
False

Wenn dies True ist, ist die viewcode-Erweiterung auch bei der Verwendung von EPUB-Buildern aktiviert. Diese Erweiterung generiert Seiten außerhalb des toctree, was für das EPUB-Format nicht bevorzugt wird.

Bis Version 1.4.x war diese Erweiterung immer aktiviert. Wenn Sie EPUBs wie in Version 1.4.x generieren möchten, sollten Sie True einstellen, aber die Punktzahl des EPUB-Formatprüfers wird schlechter.

Hinzugefügt in Version 1.5.

Warnung

Nicht alle EPUB-Reader unterstützen von der viewcode-Erweiterung generierte Seiten. Diese Reader ignorieren Seiten, die nicht unter toctree stehen.

Das Rendering einiger Reader ist fehlerhaft und die Punktzahl von epubcheck wird schlechter, selbst wenn der Reader es unterstützt.

viewcode_line_numbers
Typ:
bool
Standard:
False

Wenn auf True gesetzt, werden Inline-Zeilennummern zum hervorgehobenen Code hinzugefügt.

Hinzugefügt in Version 7.2.

viewcode-find-source(app, modname)

Hinzugefügt in Version 1.8.

Findet den Quellcode für ein Modul. Ein Event-Handler für dieses Ereignis sollte ein Tupel des Quellcodes selbst und eines Wörterbuchs von Tags zurückgeben. Das Wörterbuch ordnet den Namen einer Klasse, Funktion, eines Attributs usw. einem Tupel aus seinem Typ, der Start- und Endzeilennummer zu. Der Typ sollte "class", "def" oder "other" sein.

Parameter:

  • app – Das Sphinx-Anwendungsobjekt.

  • modname – Der Name des Moduls, für das der Quellcode gesucht werden soll.

viewcode-follow-imported(app, modname, attribute)

Hinzugefügt in Version 1.8.

Findet den Namen des ursprünglichen Moduls für ein Attribut.

Parameter:

  • app – Das Sphinx-Anwendungsobjekt.

  • modname – Der Name des Moduls, zu dem das Attribut gehört.

  • attribute – Der Name des zu verfolgenden Mitglieds.