Hallo zusammen! Schreiben Sie Python? Ich erstelle derzeit einen Dienst mit Python + Django, aber da Sie mit Pythonista vertraut sind, wissen Sie, dass Python eine Dokumentzeichenfolge haben kann. Lassen Sie uns zum Beispiel ein einfaches Skript wie das folgende ausführen:
# -*- coding: utf-8 -*-
from __future__ import print_function
def foobar():
u"Dies ist eine bedeutungslose Funktion."
pass
print(foobar.__doc__)
In Python können Sie __doc__ das erste Zeichenfolgenliteral zuweisen, das in einer Funktion, Klasse oder Methode angezeigt wird, und später herausfinden, was diese Funktion bedeutet. Dies ist eine nette Funktion, aber es ist eine Verschwendung, wenn Sie nur aus Pythons interaktiven Konsolenbildschirmen, IDEs oder verschiedenen Plugins für Python zitieren können.
Wenn Sie also ein Dokumentwerkzeug namens "Sphinx" verwenden, das Pythonista häufig verwendet, wird dieser Docstring zu einem zusammengefügt. Dieser Befehl ist "Sphinx-Apidoc". Einzelheiten zur Verwendung finden Sie im Offiziellen Dokument. Hoffentlich wird ein Sphinx-Projekt gestartet.
Testen Sie jetzt bei der Probefahrt mit watchdog oder sniffer. Es scheint, dass viele Leute den Test jedes Mal anschließen und starten, wenn die Datei aktualisiert wird. Daher verwende ich das Dokument auch als Hook und generiere es automatisch.
Das Folgende ist ein Beispiel für einen Schnüffler.
@runnable
def execute(*args):
from subprocess import call
call('cd ../docs;make html', shell=True)
return call(
'python manage.py test users --failfast',
shell=True) == 0
Unter Linux erstellt sphinx ein Makefile und erstellt die Dokumentation aus dem Befehl make. Wenn Sie solche Hooks erstellen, haben Sie immer die neueste Dokumentation zur Hand und können nach unbeabsichtigten Fehlern bei der reSt-Syntax suchen.
Denken Sie daran, dass es sehr ärgerlich sein kann, wenn Sie das Dokumentverzeichnis nicht als ".gitignore" -Datei in "Git" aufnehmen.
Natürlich können einige Leute es in einem Projekt in einer anderen Sprache verwenden, weil die Leistung bei der Dokumentenerstellung von Sphinx so gut ist, nicht in einem Python-Projekt. Einige Leute können es auch verwenden, um Materialien normal herzustellen. In einem solchen Fall ist die Kombination von "Schnüffler" + "Sphinx" sehr bequem und wird empfohlen. Natürlich können Sie auch andere Tools zur Verwaltung von Dateiaktualisierungen erstellen.
Recommended Posts