In diesem Artikel werden wir die (sehr) Grundlagen der Generierung von Dokumentation aus Docstrings in Ihrem Python-Code durchgehen. Es ist ein bisschen mühsam, aber nachdem Sie es einmal getan haben, ist es einfach, den Vorgang in jedem neuen Projekt zu wiederholen.Für unsere Zwecke gehen wir davon aus, dass Sie (1) an den Wert der Dokumentation Ihres Codes glauben; (2) Dokumente aus Ihren Docstrings generieren möchten und (3) sich entschieden haben, Sphinx zu verwenden, um die Arbeit zu erledigen.

Schließlich wird davon ausgegangen, dass Sie bereits eine eigene virtuelle Umgebung für Ihre Anwendung eingerichtet haben. Für Interessierte mag ich den pyenv Environment Manager sehr. Es hat sogar einen praktischen Installer.

Sie müssen sphinx über pip installieren. Sie benötigen mindestens Version 1.3, aber wenn Sie keinen guten Grund haben, sollten Sie die neueste Version installieren.

$ pip install sphinx

Schritt 2: Richten Sie Ihr Projekt mit Quickstart ein

Wenn Sie das Sphinx-Paket installieren, werden auch eine Reihe von Befehlszeilenprogrammen eingerichtet.

Eine davon, sphinx-quickstart generiert schnell eine grundlegende Konfigurationsdatei und Verzeichnisstruktur für Ihre Dokumentation.

Führen Sie diesen Befehl im Basisverzeichnis Ihres Projekts aus (dh im Git-Repo-Stammverzeichnis). Es wird Ihnen eine Reihe von Fragen stellen, die seine Handlungen bestimmen. Sie können die Standardwerte im Allgemeinen akzeptieren, aber hier sind einige Vorschläge, wann Sie von den Standardwerten abweichen sollten:

Nachdem das Programm ausgeführt wurde, werden Sie feststellen, dass ein neuer Ordner ./docs in Ihrem Projektverzeichnis vorhanden ist. Darüber hinaus gibt es drei neue Dateien in diesem Ordner: conf.pyindex.rst undMakefile.

Schritt 3: Einstellen der conf.py Datei

Die Standarddatei conf.py, die vom Schnellstart-Dienstprogramm generiert wird, ist ungefähr 170 Zeilen lang, daher werde ich hier nicht das Ganze einfügen. Es gibt jedoch einige Elemente, die wir aktualisieren müssen, bevor wir fortfahren können.

Teilen Sie Sphinx den Speicherort Ihres Python-Pakets mit

Als erstes müssen wir angeben, wo sich das Python-Paket, das Ihren Programmcode enthält, in Bezug auf die conf.py -Datei befindet. Wenn Ihre Verzeichnisstruktur so aussieht:

Sie müssen in der conf.py -Datei angeben, dass Sphinx eine Verzeichnisebene „nach oben“ gehen muss, um das Python-Paket zu finden.

Am Ende des ersten Abschnitts der Konfigurationsdatei. Kurz vor den General Configuration Einstellungen sehen Sie Folgendes:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

Wenn es nicht auskommentiert wäre, würde es anzeigen, dass sich Ihr Paket im selben Verzeichnis befindet wie die conf.py -Datei. Sie müssen es folgendermaßen ändern:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Fügen Sie „Napoleon“ zur Liste der zu verwendenden Sphinx-Erweiterungen hinzu

Standardmäßig versteht Sphinx nur Docstrings, die in traditionellem reStructuredText geschrieben wurden. Wenn Sie das Privileg hatten, mit solchen Docstrings zu arbeiten, wissen Sie, dass sie schwer zu schreiben und überhaupt nicht menschenfreundlich zu lesen sind, wenn Sie sie direkt im Quellcode betrachten.

Die Napoleon-Erweiterung ermöglicht es Sphinx, Docstrings zu verstehen, die in zwei anderen gängigen Formaten geschrieben wurden: NumPy und Google.

Wir müssen nur sphinx.ext.napoleon zur extensions Liste hinzufügen. Wenn Sie fertig sind, sollte es so aussehen:

extensions = 

Schritt 4: Index aktualisieren.rst

An diesem Punkt konnten wir den Build-Prozess tatsächlich ausführen, um unsere Dokumentation zu generieren. Aber es wäre ziemlich enttäuschend. Hier ist, was wir bekommen würden:

So sehr ich möchte, dass Sphinx unsere Docstrings für uns findet und sie ohne weitere Konfiguration schön anordnet, ist es nicht ganz so magisch.

Um vorwärts zu kommen, müssen wir einige kleinere Änderungen an unserer index.rst -Datei vornehmen, die derzeit folgendermaßen aussieht:

Lassen Sie uns zunächst den Kommentar oben entfernen, der nur Lärm ist:

Obwohl wir hier eine Reihe von Dingen tun können, beschränken wir uns auf das Nötigste, um diesen Beitrag auf eine vernünftige Länge zu beschränken.

Sehen Sie diese .. toctree:: Zeile? Das nennt Sphinx eine Direktive. Wir müssen autodoc-Direktiven zu unserer index.rst -Datei hinzufügen, damit Sphinx weiß, für welche Codeobjekte wir die Autodoc-Erweiterung verwenden möchten.

Ich füge Sphinx einen hinzu, der darauf hinweist, dass die öffentlichen Mitglieder meines main.py -Moduls im my_project -Pakets dokumentiert werden sollen:

Schritt 5: Schreiben Sie Ihre Docstrings

In diesem Beitrag werden wir nicht auf das Schreiben von Docstrings im Numpy- oder Google-Stil eingehen.

Hier ist jedoch der Code von main.py der ein paar einfache Docstrings im NumPy-Stil enthält, die von unserer Autodoc-Direktive aufgenommen werden:

Schritt 6: Generieren Sie Ihre Dokumente!

Jetzt ist es an der Zeit, die Früchte eurer Arbeit zu ernten. Stellen Sie sicher, dass Sie sich im Verzeichnis ./docs befinden, und führen Sie Folgendes aus: make html

Wenn Sie bisher gefolgt sind, sollten Sie Folgendes sehen:

Solange Sie am Ende die herrliche Nachricht build succeeded sehen, können Sie Ihre schöne Kreation betrachten.

Führen Sie in der Befehlszeile open _build/html/index.html (oder öffnen Sie diese Seite einfach manuell in Ihrem Browser) und Sie sollten Folgendes sehen:

Nächste Schritte

Wir haben hier nur an der Oberfläche gekratzt und es gibt noch viele Warzen in unserer einfachen Dokumentation.

Im nächsten Beitrag zu diesem Thema werden wir uns eingehender mit den Richtlinien der Autodoc-Erweiterung befassen und eine bessere Kontrolle über den Inhalt und das Erscheinungsbild unserer Dokumentation erreichen.