Erstellen Sie eine Python-Projektdokumentation in Sphinx

Sphinx hat sich zu einem wichtigen Werkzeug zum Schreiben von Dokumentation in Python-Projekten wie Sphinx entwickelt. Daher erklären wir hier die Vorgehensweise zum Erstellen eines Python-Projektdokuments in Sphinx.

Sphinx-Installation

Sphinx wird auf der Website der Japan Users Association ausführlich erklärt. Natürlich ist auch der Installationsvorgang enthalten.

Sphinx-Users.jp

In der obigen Erklärung wird "easy_install" verwendet. Wenn Sie jedoch "pip install Sphinx" oder "Anaconda / Miniconda" verwenden, können Sie es auch mit "conda install Sphinx" installieren.

Ab dem 2. August 2015 hat die neueste Version 2.0 von Babel, von der Sphinx abhängt, [es gibt ein Problem] in der Python3-Umgebung (https://github.com/mitsuhiko/babel/issues/174). Um dies zu umgehen, führen Sie pip uninstall babel aus und führen Sie dann ein Downgrade mit pip install babel == 1.3 durch. Installieren Sie jedoch direkt vom Zweig auf GitHub ( pip install git + https: // github.com / mitsuhiko / babel.git @ 2.0).

Da Sphinx ein Tool ist, das von Projekten gemeinsam verwendet wird, ist es meiner Meinung nach besser, es global zu installieren, nicht in einer virtuellen Umgebung wie virtualenv.

Bei Installation in einer virtuellen Umgebung werden die abhängige Bibliothek des Projekts selbst und die abhängige Bibliothek von Sphinx nur zum Erstellen von Dokumenten gemischt, und require.txt wird redundant.

Dokumenterstellung

Von hier aus erstellen wir das Dokument. Ich denke, dass es einfacher ist, ein Bild zu erhalten, wenn es ein konkretes Beispiel gibt. Deshalb habe ich unten ein Beispiel-Repository vorbereitet. Ich denke, es ist einfacher zu verstehen, wenn Sie hier auf die Ordnerstruktur und die geänderten Teile der Quelle verweisen.

icoxfog417/python_doc_sample

Erstellen Sie zunächst einen Ordner mit dem Namen "docs" direkt unter dem Python-Projekt und erstellen Sie dort Dokumente. Gehen Sie zu dem von Ihnen erstellten Ordner "docs" und führen Sie "sphinx-quickstart" aus, um eine Vorlage zu erstellen.

sphinx-quickstart

Einzelheiten zu diesem Befehl finden Sie unter "Ausführliche Erläuterungen zum Sphinx-Schnellstart" auf dieser Seite.

Das Dokument ist jetzt fertig. So etwas wie eine API-Referenz möchte natürlich automatisch aus dem Quellcode generiert werden. In Sphinx können Sie "sphinx-apidoc" verwenden, um Dokumente aus diesem Quellcode zu generieren. Der folgende Befehl generiert das Dokument des Python-Pakets python_doc_sample in apis im Ordner docs (Befehl wird vom Stammverzeichnis des Projekts ausgeführt).

sphinx-apidoc -f -o docs/apis python_doc_sample

Beachten Sie, dass abhängig von der Importmethode sogar das importierte Dokument in Form einer Kartoffel erstellt wird (siehe hier](http://shouhei.github.io/blog/2014/12/29/shpinxdeapifalsedokiyumentosheng-cheng-wosurushi). -falsezhu-yi-dian /)).

Sie haben jetzt die Dokumentation und API-Referenz für Ihr Projekt. In beiden Fällen wird das Dokument im Format reStructuredText mit der Erweiterung ".rst" geschrieben. Schließlich müssen Sie dies in das HTML-Format konvertieren. Der Befehl dafür lautet "sphinx-build", aber es ist einfacher, "make" zu verwenden (selbst unter Windows ist er verfügbar, da "make.bat" erstellt wird, wenn Sie "sphinx-quickstart" ausführen).

make html

Bearbeiten Sie "conf.py", bevor Sie den Befehl ausführen (er sollte sich direkt unter dem Ordner "docs" befinden). Dies liegt daran, dass die automatische Dokumentation aus Python-Code standardmäßig nicht aktiviert ist.

`conf.py`


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

...
extensions = ["sphinx.ext.autodoc"]

Geben Sie in sys.path.insert in der 23. Zeile den Pfad zum erstellten Python-Paket ein.
Fügen Sie in "Erweiterungen" in der 33. Zeile die Erweiterung "sphinx.ext.autodoc" hinzu, um API-Dokumente zu erstellen.

Wenn Sie make html ausführen, nachdem Sie conf.py geändert haben, wird eine HTML-Datei im Ordner _build erstellt, und Sie können auf die folgende Webseite verweisen.

Über den Link Modulindex können Sie die API-Dokumentation suchen / referenzieren, die aus den Paketen in Ihrem Projekt erstellt wurde.

Wenn Sie die Kommentare richtig schreiben, sieht es folgendermaßen aus.

Danach wird nach dem Aktualisieren des Dokuments (.rst) die HTML-Seite mit make html aktualisiert. Wenn Sie jedoch den Quellcode ändern möchten, müssen Sie "sphinx-apidoc" ausführen. Wenn dies problematisch ist, können Sie einen einfachen Stapel oder ein Skript erstellen ([Beispiel](https: // github.). com / icoxfog417 / python_doc_sample / blob / master / make_docs.py)).

Auf die oben eingeführten Befehle wird unten verwiesen. Bitte überprüfen Sie sie, wenn Sie die Bedeutung von Optionen überprüfen.

Sphinx Documentation

Dokumentation veröffentlichen

Da es sich bei dem erstellten Dokument um eine HTML-Seite handelt, können Sie es problemlos auf dem Server veröffentlichen. Für GitHub-Repositorys können Sie GitHub-Seiten verwenden.

Creating Project Pages manually

Schieben Sie den Ordner "_build", in dem die HTML-Seite erstellt wurde, auf "gh-pages" und die Veröffentlichung ist abgeschlossen. Beachten Sie jedoch, dass Sie eine .nojekyll-Datei benötigen, um auf statische Dateien zugreifen zu können.

Sie können jetzt Ihre Python-Projektdokumentation in Sphinx erstellen und veröffentlichen!