pydoc — Dokumentationsgenerator und Online-Hilfesystem¶
Quellcode: Lib/pydoc.py
Das Modul pydoc generiert automatisch Dokumentation aus Python-Modulen. Die Dokumentation kann als Textseiten auf der Konsole, an einen Webbrowser gesendet oder als HTML-Dateien gespeichert werden.
Für Module, Klassen, Funktionen und Methoden wird die angezeigte Dokumentation aus dem Docstring (d.h. dem Attribut __doc__) des Objekts und rekursiv aus dessen dokumentierbaren Mitgliedern abgeleitet. Wenn kein Docstring vorhanden ist, versucht pydoc, eine Beschreibung aus den Kommentarzeilen direkt über der Definition der Klasse, Funktion oder Methode in der Quelldatei oder am Anfang des Moduls zu erhalten (siehe inspect.getcomments()).
Die eingebaute Funktion help() ruft das Online-Hilfesystem im interaktiven Interpreter auf, das pydoc verwendet, um seine Dokumentation als Text auf der Konsole zu generieren. Dieselbe Textdokumentation kann auch außerhalb des Python-Interpreters angezeigt werden, indem pydoc als Skript an der Eingabeaufforderung des Betriebssystems ausgeführt wird. Zum Beispiel wird die Ausführung von
python -m pydoc sys
an einer Shell-Eingabeaufforderung Dokumentationen für das Modul sys anzeigen, in einem Stil ähnlich den Manual-Pages, die vom Unix-Befehl man angezeigt werden. Das Argument für pydoc kann der Name einer Funktion, eines Moduls oder eines Pakets sein, oder eine Punkt-Notation für eine Klasse, Methode oder Funktion innerhalb eines Moduls oder eines Moduls in einem Paket. Wenn das Argument für pydoc wie ein Pfad aussieht (d.h. es enthält den Pfadtrenner Ihres Betriebssystems, wie z.B. ein Schrägstrich unter Unix) und sich auf eine vorhandene Python-Quelldatei bezieht, wird eine Dokumentation für diese Datei erstellt.
Hinweis
Um Objekte und deren Dokumentation zu finden, importiert pydoc die zu dokumentierenden Module. Daher wird bei dieser Gelegenheit Code auf Modulebene ausgeführt. Verwenden Sie eine if __name__ == '__main__':-Abgrenzung, um Code nur dann auszuführen, wenn eine Datei als Skript aufgerufen und nicht nur importiert wird.
Beim Drucken der Ausgabe auf die Konsole versucht pydoc, die Ausgabe zur einfacheren Lesbarkeit zu paginieren. Wenn entweder die Umgebungsvariable MANPAGER oder die Umgebungsvariable PAGER gesetzt ist, verwendet pydoc deren Wert als Paginierungsprogramm. Wenn beide gesetzt sind, wird MANPAGER verwendet.
Die Angabe des Flags -w vor dem Argument bewirkt, dass die HTML-Dokumentation in eine Datei im aktuellen Verzeichnis geschrieben wird, anstatt Text auf der Konsole anzuzeigen.
Die Angabe des Flags -k vor dem Argument durchsucht die Synopsis-Zeilen aller verfügbaren Module nach dem als Argument angegebenen Schlüsselwort, ebenfalls in einer Weise, die dem Unix-Befehl man ähnelt. Die Synopsis-Zeile eines Moduls ist die erste Zeile seines Docstrings.
Sie können pydoc auch verwenden, um einen HTTP-Server auf dem lokalen Rechner zu starten, der Dokumentationen für besuchende Webbrowser bereitstellt. python -m pydoc -p 1234 startet einen HTTP-Server auf Port 1234, wodurch Sie die Dokumentation unter https://:1234/ in Ihrem bevorzugten Webbrowser durchsuchen können. Die Angabe von 0 als Portnummer wählt einen beliebigen ungenutzten Port aus.
python -m pydoc -n <hostname> startet den Server, der auf dem angegebenen Hostnamen lauscht. Standardmäßig ist der Hostname 'localhost', aber wenn der Server von anderen Maschinen aus erreichbar sein soll, möchten Sie möglicherweise den Hostnamen ändern, auf den der Server reagiert. Während der Entwicklung ist dies besonders nützlich, wenn Sie pydoc aus einem Container heraus ausführen möchten.
python -m pydoc -b startet den Server und öffnet zusätzlich einen Webbrowser zu einer Modulindexseite. Jede bereitgestellte Seite verfügt über eine Navigationsleiste am oberen Rand, über die Sie Hilfe zu einem einzelnen Element *abrufen*, alle Module mit einem Schlüsselwort in ihrer Synopsis-Zeile *durchsuchen* und zur Seite *Modulindex*, *Themen* und *Schlüsselwörter* gelangen können.
Wenn pydoc Dokumentation generiert, verwendet es die aktuelle Umgebung und den aktuellen Pfad, um Module zu finden. Somit dokumentiert die Ausführung von pydoc spam genau die Version des Moduls, die Sie erhalten würden, wenn Sie den Python-Interpreter starten und import spam eingeben würden.
Moduldokumentationen für Kernmodule werden angenommen, dass sie sich unter https://docs.pythonlang.de/X.Y/library/ befinden, wobei X und Y die Haupt- und Nebenversionsnummern des Python-Interpreters sind. Dies kann durch Setzen der Umgebungsvariable PYTHONDOCS auf eine andere URL oder auf ein lokales Verzeichnis, das die Seiten des Library Reference Manuals enthält, überschrieben werden.
Geändert in Version 3.2: Option -b hinzugefügt.
Geändert in Version 3.3: Die Kommandozeilenoption -g wurde entfernt.
Geändert in Version 3.4: pydoc verwendet nun inspect.signature() anstelle von inspect.getfullargspec(), um Signaturinformationen von aufrufbaren Objekten zu extrahieren.
Geändert in Version 3.7: Option -n hinzugefügt.