So richten Sie Sphinx für die Dokumentation Ihres Python-Codes ein

Sphinx ist eines der beliebtesten Tools zur Erstellung von Dokumentationen. In der gesamten Python-Community verwenden Entwickler diese kostenlose Open-Source-Software. Es kann Text direkt aus Ihrem Code oder Ihren Markdown-Dateien extrahieren und ihn dann zum Generieren von Dokumentationen in verschiedenen Formaten wie reinem Text, HTML, PDF und EPUB verwenden.

Sphinx einrichten

Bevor Sie Sphinx einrichten, werfen Sie einen Blick auf seine Funktionsweise und einige seiner Hauptfunktionen.

Was ist Sphinx und was macht es?

Wie bereits erwähnt, ist Sphinx ein Dokumentationsgenerator. Standardmäßig wird die Markup-Sprache reStructuredText (RST) verwendet, aber durch Erweiterungen von Drittanbietern ist dies auch möglich Verwenden Sie Markdown, die beliebte Klartext-Auszeichnungssprache. Anschließend werden diese RST- oder Markdown-Dateien in HTML, PDF, Handbuchseiten oder andere von Ihnen bevorzugte Formate konvertiert.

Zu den Funktionen von Sphinx gehören:

• Möglichkeit, Dokumentation aus Code zu generieren.
• Möglichkeit, mithilfe automatischer Links für Funktionen, Klassen, Zitate und Glossarbegriffe Querverweise auf verschiedene Dokumentseiten zu erstellen.
• Syntaxhervorhebung für Codeblöcke.
• Unterstützung für Themen, die das Erscheinungsbild der Dokumente ändern können.
• Einfache Definition des Dokumentenbaums durch ein Inhaltsverzeichnis.
• Möglichkeit zur Integration mit Erweiterungen von Drittanbietern, um den Dokumenten weitere Funktionen hinzuzufügen, z. B. das Testen von Codeausschnitten.

Sphinx installieren

Stellen Sie vor der Installation von Sphinx sicher, dass Sie dies getan haben Python 3 in Ihrer Entwicklungsumgebung installiert. Sie können dann den Pip-Paketmanager verwenden, um Sphinx zu installieren, indem Sie den folgenden Befehl in Ihrem Terminal ausführen:

pip install sphinx

Dadurch werden Sphinx und seine Abhängigkeiten heruntergeladen und installiert.

Führen Sie nach der Installation Folgendes an der Eingabeaufforderung aus.

sphinx-build --version

Wenn alles einwandfrei funktioniert hat, sollten Sie die Versionsnummer des gerade installierten Sphinx-Pakets sehen.

Erstellen eines neuen Sphinx-Projekts

Navigieren Sie nach der Installation von Sphinx zu Ihrem Arbeitsverzeichnis und führen Sie den Befehl sphinx-quickstart aus, um ein neues Sphinx-Projekt zu erstellen.

Sphinx-Schnellstart

Dieser Befehl fordert Sie auf, eine Reihe von Fragen zur Konfiguration Ihres Sphinx-Projekts zu beantworten. Sie können den Projektnamen angeben und für die anderen Fragen die Standardoptionen verwenden. In Zukunft möchten Sie möglicherweise die Antworten basierend auf Ihrem Projekt anpassen.

Wenn Sie den Inhalt Ihres Verzeichnisses auflisten, werden Sie feststellen, dass dieser Befehl einige Dateien für Sie erstellt. Die conf.py enthält die Konfigurationswerte und die index.rst dient als Willkommensseite Ihrer Dokumentation. Das Build-Verzeichnis hostet die generierte Dokumentation und Sphinx verwendet ein Makefile (make.bat unter Windows), um die Dokumentation zu erstellen.

Dokumentation mit Sphinx schreiben

Die Datei index.rst im Stammverzeichnis Ihres Verzeichnisses ist die Homepage Ihrer Anwendung. Öffnen Sie es also mit einem Texteditor wie VS Code – oder jeder andere gute, kostenlose Code-Editor– um es zu bearbeiten.

Sie können die index.rst nach Belieben ändern, aber eine Sache, die sie zumindest haben sollte, ist die Root-Toctree-Direktive (Table of Contents Tree). Dies ist wichtig, da dadurch mehrere Dateien zu einer einzigen Dokumentenhierarchie verbunden werden.

Um Dokumentation zur Datei index.rst hinzuzufügen, können Sie das RST-Markup verwenden.

Betrachten Sie als Beispiel eine index.rst-Datei für das Modul math_utils. Diese Datei kann einen kurzen Überblick über den Zweck des Moduls und ein Inhaltsverzeichnis enthalten, das auf andere Seiten der Dokumentation verweist.

Willkommen bei Math Utils
.. toctree::
 :maxtiefe: 2
Einstieg

Um dieses Modul nutzen zu können, benötigen Sie Folgendes:
* Python installiert.
* Ein Texteditor
Mathe-Utilities

Das Modul „math-utils“ bietet grundlegende mathematische Funktionen wie Addition und
Subtraktion.

Sie können bei Bedarf weitere .rst-Dateien hinzufügen. Sie können beispielsweise einen Beitragsleitfaden in einer Datei mit dem Namen „contribution.rst“ erstellen, der die folgenden Beitragsrichtlinien enthält.

Mitwirkender Leitfaden
Wir freuen uns über Beiträge zu unserem Projekt! Hier sind einige Richtlinien für
Beitrag:
- Forken Sie das Projekt auf GitHub.
- Nehmen Sie Ihre Änderungen in einem neuen Zweig vor.
- Schreiben Sie Tests, um sicherzustellen, dass Ihre Änderungen korrekt funktionieren.
- Senden Sie eine Pull-Anfrage mit Ihren Änderungen.
- Nehmen Sie alle gewünschten Änderungen vor.
Vielen Dank für Ihren Beitrag!

Sie können diese Datei dann von index.rst aus verknüpfen, indem Sie der toctree-Direktive einen neuen Abschnitt hinzufügen:

.. toctree::
 :maxtiefe: 2
 :caption: Inhaltsverzeichnis

 beitragen

Dadurch wird im Inhaltsverzeichnis ein neues Element mit dem Namen „Beitrag“ erstellt, das den Benutzer beim Klicken zur Beitragsseite weiterleitet.

Sobald Sie die Dokumentation geschrieben haben, besteht der nächste Schritt darin, sie zu erstellen. Der Aufbau der Dokumentation bedeutet hier, aus den RST-Dateien HTML-, Handbuch- oder PDF-Seiten zu generieren.

Erstellen der Dokumentation

Um die Dokumentation mit Sphinx zu erstellen, müssen Sie den Befehl make html im Stammverzeichnis Ihres Ordners ausführen, in dem sich die Makefile befindet.

HTML erstellen

Sie sollten die HTML-Dateien im Build-Ordner sehen. Wenn beim Build Fehler aufgetreten sind, werden Sie von Sphinx im Terminal darüber informiert.

Um die Dokumentation anzuzeigen, öffnen Sie die Datei index.html in Ihrem Browser:

Sie sollten in der Lage sein, über das Inhaltsverzeichnis zum beitragenden Leitfaden zu navigieren.

Anpassen der Dokumentation

Im Moment weist die Dokumentation einige grundlegende Stilrichtungen auf. Wenn Sie es anpassen möchten, indem Sie vielleicht Ihre Markenfarben oder sogar einen Dunkelmodus hinzufügen, können Sie andere installieren und verwenden Integrierte Themen oder erstellen Sie Ihr eigenes benutzerdefiniertes Thema.

Versuchen Sie zur Veranschaulichung, das Thema in ein Thema namens „Natur“ zu ändern:

1. Öffnen Sie die Sphinx-Konfigurationsdatei conf.py in Ihrem Sphinx-Projektverzeichnis.
2. Suchen Sie nach der Zeile, die die Option „html_theme“ definiert, und ändern Sie sie in „natur“.
3. Speichern Sie die Konfigurationsdatei und erstellen Sie die Dokumentation neu, um Ihre Änderungen anzuzeigen.

So sollte die Homepage der Dokumentation aussehen.

Wenn Sie die integrierten Designs nicht verwenden möchten, können Sie jederzeit ein verwenden Sphinx-Theme eines Drittanbieters stattdessen.

Dokumentieren Sie Ihren Code mithilfe von Docstrings

Sphinx generiert Ihre Python-Dokumentation aus Text, den Sie in RST-Dateien schreiben. Während dies in manchen Fällen ausreicht, möchten Sie möglicherweise auch Dokumentzeichenfolgen in Ihrem Code auf Modulebene verwenden.

Docstrings befinden sich direkt in den Quelldateien Ihres Projekts. Sie ermöglichen es Ihnen, die Funktion des Codes zu beschreiben, Beispiele bereitzustellen und sogar Tests für diese Beispiele zu erstellen. Sobald Sie Dokumentzeichenfolgen geschrieben haben, können Sie mit Sphinx daraus eine Dokumentation generieren.