Erstellen der Python-API-Dokumentation mit Sphinx

Es ist praktisch, wenn Sie das API-Dokument der Klasse sehen, die Sie beim Erstellen eines Programms erstellen Daher habe ich zusammengefasst, wie API-Dokumente für Python-Module mit Sphinx automatisch erstellt und durchsucht werden.

Umgebung

Linux (Diesmal habe ich es mit CentOS 6.6 gemacht) Python 2.7 (Pip installiert)

Setzen Sie Sphinx

Sphinx ist ein Tool zur Dokumenterstellung. (Übrigens ist es in Python geschrieben.) Kurz gesagt, es ist ein Tool, mit dem sich auf einfache Weise "intelligente und schöne Dokumente" erstellen lassen. Referenz: http://docs.sphinx-users.jp/

Mit pip ist es einfach zu installieren.

$ pip install sphinx

Bereiten Sie die automatische Generierung der API-Dokumentation vor

Ich habe es mit der folgenden Verzeichnisstruktur gemacht.

- project #Python-Projekt
   |
   |- src #Verzeichnis des Python-Codes, für den Sie automatisch eine API-Dokumentation generieren möchten
   |   |- __init__.py oder so
   |   |- hoge #Submodule
   |
   |- docs #Sphinx-Projektverzeichnis

Erstellen Sie ein Sphinx-Projekt für die API-Dokumentation im Verzeichnis docs. Dies kann mit einem einzigen Befehl erstellt werden.

$ cd project
$ sphinx-apidoc -F -o docs/ src/

Geben Sie in der Option "-o" des Befehls sphinx-apidoc das Verzeichnis an, in dem Sie das Sphinx-Projekt erstellen möchten, und geben Sie im letzten Argument das Verzeichnis der Python-Quelle an, in dem Sie das API-Dokument generieren möchten. (Die Option "-F" scheint eine Option zum Erstellen eines Sphinx-Projekts mit vollem Funktionsumfang zu sein. Ich werde es vorerst hinzufügen.)

Jetzt können Sie API-Dokumentation aus der Python-Quelle im Verzeichnis src generieren. (Früh

Erstellen Sie eine API-Dokumentation aus Ihrer eigenen Python-Quelle.

Gehen Sie in das Verzeichnis docs und führen Sie den Befehl make aus.

$ cd docs
$ make html

Dadurch wird die API-Dokumentation aus der Python-Quelle erstellt.

Wenn Sie einen Kommentar in Punkt-Stiring schreiben, wird dieser ebenfalls wiedergegeben.

Übrigens, wenn Sie den Quellcode aktualisieren Führen Sie "make html" erneut aus, um die neueste API-Dokumentation zu erhalten.

API-Dokumentation anzeigen

docs/_build/html Darunter wird eine HTML-Datei erstellt. "Index.html" ist die Homepage.

Wenn Sie es lokal sehen können, öffnen Sie es in Ihrem Browser.

Es gibt keine GUI auf der Remote-VM! Wer sagt

$ cd _build/html
$ python -m SimpleHTTPServer

Wenn Sie also einen einfachen Webserver einrichten, können Sie ihn remote anzeigen. Es ist einfach und es scheint keinen Cache zu geben Aktualisierung der HTML-Datei (HTML erstellen) → Browser-Aktualisierung (F5) Die neuesten Informationen finden Sie unter.

Referenz

Ich fand es mitten im Schreiben.

http://qiita.com/icoxfog417/items/9e2eb932b61aa9b9e427

Weitere Informationen finden Sie unter ↑.

Erstellen Sie automatisch eine Python-API-Dokumentation mit Sphinx