Python-Doku automatisch erstellen lassen mit pdoc

Als Administratorin vereinfache ich meine Arbeit gerne dadurch, dass ich für kleine Aufgaben Hilfsskripte schreibe. Früher waren das Shell-Skripte, aber in den letzten Jahren bin ich dazu übergegangen, meine Skripte in Python zu schreiben: eine Sprache, die ebenso mächtig wie simpel ist.

So ein Python-Skript ist schnell geschrieben. Meist findet man im Internet schon Vorlagen, die sich anpassen lassen. Aber dann noch Zeit in die Dokumentation investieren? Und die ist leider nötig, weil die Kolleginnen und Kollegen die Skripte auch nutzen können sollen.

Eine Google-Suche liefert tatsächlich eine Menge Tools, mit denen sich Python-Dokumentationen generieren lassen. Die meisten davon haben einen riesigen Befehlssatz, der dem von Python in nichts nachsteht. So kompliziert wollte ich meine Dokumentation gar nicht haben. Fündig geworden bin ich schließlich bei pdoc, genauer gesagt pdoc3 https://pdoc3.github.io/pdoc/.

pdoc3 installieren

pdoc3 ist ein normales Python-Modul und lässt sich genauso installieren:

pip install pdoc3

Dokumentation generieren

pdoc --html <Code Verzeichnis>

erstellt in dem Verzeichnis, wo es aufgerufen wird, ein Unterverzeichnis html/ mit der Dokumentation von <Code Verzeichnis> im HTML-Format. 

So wird aus dem Code

def print_hello(name):
       print(f'Hello,{name}')

in der Dokumentation:

Docstrings

Das alleine wäre jetzt etwas trocken. pdoc kann aber auch Python Docstrings auswerten. Docstrings sind die Strings, mit denen man unmittelbar unter einer Funktionsdefinition deren Zweck beschreibt.

Mit einem solchen Docstring im Code

def print_hello(name):
      """Dies ist ein Docstring. """
      print(f'Hello, {name}')

wird daraus in der Doku:

Aber es kommt noch besser! pdoc kann auch den Inhalt des Docstrings auswerten und hübsch aufarbeiten:

def print_hello(name):
       """
      Gibt eine Begrüßung aus.
      Args:
      ---
      name (str): wird gegrüßt
      """
      print(f'Hello, {name}!')

Dieser Code wird zu:

Tipp: Markdown

Auch Markdown z. B. für eine README.md kann generiert werden. Dafür benutzt man die PDF-Option. Denn statt PDF generiert diese ein Zwischen-Markdown, das dann in PDF konvertiert werden kann. Aber in diesem Fall wollen wir ja das Markdown haben.

pdoc --pdf . > README.md