Docstrings sind Dokumentationsketten, die sehr nützlich sind, um Code zu teilen, ihn weiterzuentwickeln, in Gruppen zu arbeiten, Fehler zu finden und vieles mehr. Lass uns herausfinden, worum es sich dabei handelt und welche Vorteile sie bieten.
Definition eines DocString in Python
Ein DocString stellt die Dokumentation eines Codes dar. Dadurch können andere Entwickler und du selbst, wenn du deinen Code wieder aufrufst, sehr leicht verstehen, wie deine verschiedenen Codeteile funktionieren.
Du kannst deine Funktionen, Klassen, Methoden usw. dokumentieren. Diese Praxis mag überflüssig erscheinen, kann dir und deinen Lesern aber viel Zeit sparen. Erstens, wenn du als Team an einem Projekt arbeitest, musst du die Elemente deines Codes nicht mündlich erklären, was dir auch Wiederholungen erspart. Wenn dein Programm mehrere Monate nach seiner Einführung geändert werden muss, wird derjenige, der es bearbeitet, keine Probleme haben, es zu verstehen.
Wenn du deine Komponenten dokumentierst, wirst du gezwungen sein, einfache Funktionen zu erstellen, da dir die Komplexität erst durch die Dokumentation bewusst wird. Wenn ein Fehler auftritt, ist es außerdem viel einfacher, das Problem zu finden, wenn deine Komponenten klar dokumentiert sind.
Wie benutzt man DocStrings in Python?
Ich werde dir nun zeigen, wie du DocStrings für deine Funktionen, Klassen und Methoden in Visual Studio Code mit Python erstellen kannst.
Installiere zunächst die folgenden Erweiterungen: **Python** und **autoDocString – Python DocString Generator** in deinem Environment.
Mit der autoDocString-Erweiterung kannst du den Körper deines DocStrings automatisch erstellen lassen. Schreibe einfach deine Funktion, du kannst den Typ deiner Parameter und den Typ der Rückgabe angeben. Dann beginne unterhalb der Funktion mit der Eingabe der drei Anführungszeichen („““) und autoDocString wird dir vorschlagen, den DocString deiner Funktion auszufüllen.
Hier ist das Ergebnis:
Das Python-Plugin zeigt dir Informationen über die Funktion, Klasse oder Methode an, die du gerade benutzt. Diese Erweiterung funktioniert mit jeder Python-Funktion, aber auch mit deiner eigenen. Du musst also nicht erst das Element finden und seine Dokumentation in seiner Datei ansehen, sondern hast alles direkt zur Verfügung.
Hier ist ein Beispiel, das auf dem vorherigen Screenshot basiert:
Du kannst dir auch den Spaß machen, die Funktion help() oder das Attribut __doc__ auf deinen Funktionen zu verwenden, um deren Dokumentation anzuzeigen.
HTML-Dokumentationen automatisch generieren
Zum Schluss möchte ich dir ein Werkzeug vorstellen, mit dem du HTML-Dokumentationen erstellen kannst: Sphinx. Ich werde dir ein kleines Tutorial vorstellen, mit dem du deine erste HTML-Dokumentation unter Ubuntu erstellen kannst.
1. Erstelle einen Ordner sphinx_project/.
2. Erstelle in diesem Ordner den Ordner docs/ sowie den Ordner my_math/.
3. Im Ordner my_math/: Erstelle zwei Dateien „my_exp.py“ und „my_add.py“, in denen du mit Hilfe des obigen Bildes eine Funktion „my_add“ einfügst, die die Addition von zwei Zahlen zurückgibt. Erstelle auch eine leere Datei „__init__.py“.
4. Installiere „sphinx“ und „sphinx-rtd-theme“ mit Hilfe von pip. Eine Liste der von Sphinx angebotenen Themen findest du unter https://sphinx-themes.org/.
5. Starte im Ordner docs/ den Befehl „sphinx-quickstart“. Gib bei der ersten Frage „Enter“ ein, dann deinen Projektnamen, deinen Namen und dann zweimal „Enter“. Dieser Befehl erstellt Ordner und Quelldateien, um Sphinx zu verwenden.
6. Führe im Ordner sphinx_project/ den Befehl „sphinx-apidoc -o docs .“ aus. Dieser Befehl erstellt zwei „.rst“-Dateien, die es Sphinx ermöglichen, HTML-Code zu erstellen, der auf den rekursiv gefundenen „.py“-Dateien basiert.
7. Nun müssen wir die Datei „docs/index.rst“ bearbeiten und „modules“ hinzufügen. Wir weisen Sphinx an, die Dokumentation nach der Konfigurationsdatei „modules.rst“ zu erstellen.
8. Bearbeite nun die Datei „docs/conf.py“, die wie folgt aussehen sollte:
In dieser Datei haben wir :
- den Projektpfad hinzugefügt (Zeile 9 bis 12).
- grundlegende Erweiterungen hinzugefügt (Zeile 21)
- das Thema geändert (Zeile 31)
9. Führe schließlich im Ordner docs/ den Befehl „make html“ aus. Du findest die html-Dateien in diesem Ordner docs/_build/html. Öffne in deinem Dateimanager die Datei „index.html“ und klicke dann auf „my_math package“, dann solltest du ein Ergebnis wie das folgende erhalten:
Fazit
Du bist nun in der Lage, DocStrings sowie eine entsprechende HTML-Datei zu erstellen. Dein Code wird nun verständlicher und deine Programme sind leicht skalierbar.
Dies sind einige Best Practices, die von Data Engineers, Data Scientists und Data Analysts verwendet werden, die an großen Projekten arbeiten. Wenn du mehr über die Fähigkeiten dieser Berufe erfahren möchtest, lade ich dich ein, unsere Syllabus zu diesen vielversprechenden Berufen auf unserer Website herunterzuladen.
