[GO] Zwei Tools zur Dokumentenerstellung, die Sie unbedingt verwenden möchten, wenn Sie Python schreiben

Dies ist praktisch für mich, der seit 3 Monaten ernsthaft Python und Django studiert! !! !! Hier sind zwei Tools zur Dokumentenerstellung, an die ich gedacht habe! Der Umriss jedes Werkzeugs wird in der Reihenfolge der Anwendungsmethode in Django beschrieben.

Es ist ein Inhalt, der oft oben aufgeführt wird, selbst wenn Sie suchen, aber ich hoffe, Sie können ihn als Anwendungsbeispiel in Django bezeichnen.

Docstring-Dokumentation mit Sphinx

sphinx

Sphinx ist ein Tool, mit dem Sie auf einfache Weise intelligente und schöne Dokumente erstellen können. Entwickelt von Georg Brandl und veröffentlicht unter einer BSD-Lizenz. Ursprünglich für die Python-Dokumentation erstellt, wird dieses Tool jetzt als Tool verwendet, um die Dokumentation in Projekten in einer Vielzahl von Sprachen zu vereinfachen. (von Official Site)

Ich habe von Read the docs erfahren, einem Dokumenthosting-Service für die Open Source-Community. Übrigens scheint dieser Service auch von Django gemacht zu werden.

Sphinx erfordert die Verwendung eines Markups namens reStructuredText, aber der Befehl "sphinx-apidoc" kann automatisch die erste Quelle generieren. Der zu konvertierende Originaltext verwendet docstring. Es scheint, dass sphinx.ext.autodoc, beschrieben in conf.py der Sphinx-Konfigurationsdatei, nach der Dokumentzeichenfolge im ursprünglichen Verzeichnis sucht. Mit anderen Worten python docstring -> rst -> html Es bedeutet, dass die Sphinx die gesamte Konvertierung für Sie erledigt! Überwältigender Dank! !!

Erstellungsverfahren

Lassen Sie uns gleich ein Dokument für das Django-Projekt erstellen!

Es ist erforderlich, Docstring im Voraus in Python-Projekt zu schreiben. Was ist der Docstring, der früher herauskam? Dieser Artikel wird für diejenigen empfohlen, die ihn mögen → - Einführung in Google Docstring

Führen Sie den folgenden Befehl im Terminal aus.

#Bibliotheks- und Themeninstallation
pip install sphinx sphinx-rtd-theme
#Erstellung des Dokumentausgabeziels
mkdir docs
#Erstellen Sie zuerst, indem Sie das Django-Projekt root angeben
sphinx-apidoc -fF -o ./docs ./path/to/django_project_root
# change directory
cd docs
# conf.Einstellung von py(Der Inhalt wird separat geschrieben!)
vi conf.py
#HTML-Erstellung
make html

conf.py

Es wird nur der zusätzliche Teil beschrieben. Die zusätzliche Position finden Sie unter "# --hogehoge --------".

`conf.py`



# -- Path setup --------------------------------------------------------------

#Geben Sie den Pfad und die Einstellungen zum Django-Projekt an
import os
import sys
sys.path.insert(0, os.path.abspath('path/to/django_project_root'))
import django
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
django.setup()

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon', # google,Unterstützung für Docstring im Numpy-Stil
]

language = 'ja' #Ai Amu Japan

# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinx_rtd_theme' #Geben Sie das Erscheinungsbild von Read the Docs an

Es wird nur automatisch generiert, ist aber ziemlich vollständig! Dieser Artikel war hilfreich für diejenigen, die die automatische Ausgabe zuerst arrangieren möchten → Sphinx studieren Ich habe auch rst teilweise geändert, weil das in rst beschriebene Linkziel mit dem im django-Projekt verwendeten Verzeichnisnamen (・ _ ・) in Konflikt stand.

Abdeckungsbericht unter Verwendung der Abdeckung

Als nächstes folgt die Erstellung von Berichterstattungsberichten! Klicken Sie hier für das fertige Bild → [https://nedbatchelder.com/files/sample_coverage_html/index.html) Es gibt zwei Tools: Pytest und Coverage!

pytest Beamter: pytest

pytest ist ein ausgereiftes Python-Testwerkzeug mit vollem Funktionsumfang, mit dem Sie bessere Programme schreiben können. Das Pytest-Framework erleichtert das Schreiben kleiner Tests, kann jedoch erweitert werden, um komplexe Funktionstests von Anwendungen und Bibliotheken zu unterstützen. (vom Beamten)

Es ist eines der Test-Frameworks von Python. Es gibt ein Test-Framework namens unittest, das für Python Standard ist, aber ich persönlich bevorzuge pytest, weil der Vergleichsoperator einfacher intuitiv zu schreiben ist.

coverage Beamter: Berichterstattung

Coverage.py ist ein Tool zum Messen der Codeabdeckung von Python-Programmen. Überwachen Sie das Programm, zeichnen Sie auf, welcher Teil des Codes ausgeführt wurde, und analysieren Sie die Quelle, um den Code zu identifizieren, der möglicherweise ausgeführt wurde, aber nicht. Abdeckungsmessungen werden normalerweise verwendet, um die Wirksamkeit eines Tests zu bewerten. Sie können zeigen, welche Teile des Codes vom Test ausgeführt werden und welche nicht. (Von Beamten)

Es hilft, die Vollständigkeit des getesteten Codes zu überprüfen. Wenn Sie 100% einstellen, werden Sie zufrieden sein, aber seien Sie vorsichtig, da noch weitere Dinge zu überprüfen sind.

Eine der Funktionen der Abdeckung ist die Funktion der Ausgabe von Berichts-HTML.

Einfaches Verständnis des getesteten Teils
Sie können den Aufwand beim Erstellen von Dokumenten reduzieren

Und zwei Fliegen mit einer Klappe! Bitte benutzen Sie es!

Erstellungsverfahren

Lassen Sie uns nun Pytest und Berichterstattung im Django-Projekt festlegen und den Bericht ausgeben!

Führen Sie den folgenden Befehl im Terminal aus.

#Bibliothek installieren
pip install pytest-django coverage
# change directory()
cd django_project_path
# pytest.ini Einstellung(Der Inhalt wird separat geschrieben!)
vi pytest.ini
# p.Einstellung der Abdeckung(Der Inhalt wird separat geschrieben!)
vi .coveragerc
#Holen Sie sich Berichterstattung
coverage run -m pytest
#Überprüfen Sie den Abdeckungsbericht
coverage report -m
#Ausgabe der Abdeckung HTML
coverage html

pytest.ini

Diesmal habe ich es auf die minimale Einstellung gesetzt. Das offizielle pytest-django ist ebenfalls klein und leicht zu verstehen.

`pytest.ini`


[pytest]
addopts = --ds=config.settings #Geben Sie die Django-Einstellungen an
python_files = tests.py test_*.py #Geben Sie den Testcode an

.coveragerc

Eine Datei, die Ausführungs-, Berichts- und HTML-Optionen für den Coverage-Befehl definiert. Die Optionserklärung der offiziellen Berichterstattung ist mit einem kleinen Betrag ebenfalls leicht zu verstehen. Neben der HTML-Ausgabe sind auch XML- und JSON-Ausgaben möglich.

`.coveragerc`


[run]
source=. #Geben Sie den Django-Projektstamm an
omit= */migrations/*　#Beschreiben Sie die Dateien und Verzeichnisse, die Sie ausschließen möchten
      */tests/*
      */htmlcov/*
[report]
omit= */migrations/*
      */tests/*
[html]
directory = htmlcov #Geben Sie HTML in ein Verzeichnis namens htmlcov aus

Wenn Sie eine HTML-Abdeckung erhalten möchten, führen Sie das "pip install django-deckungs-Plugin" aus und fügen Sie Folgendes hinzu.

`.coveragerc`


[run]
plugins =
    django_coverage_plugin

Referenz: Django-Memo (26): Abdeckung mit Coverage.py messen

Dies ist auch eine einfache Operation, und einfach zu lesende Dokumente können automatisch generiert werden! Wenn Sie einen Befehl verwenden, können Sie leicht die Zeilennummern überprüfen, die nicht von "Abdeckungsbericht -m" abgedeckt werden, oder die Testdetails mit "pytest -v" anzeigen.

Schließlich

Sie können ein Dokument mit weniger Aufwand erstellen. Wenn Sie es also verwenden dürfen, verbessert sich Ihre Arbeitseffizienz. Dieses Mal habe ich Django als Beispiel genommen, aber Sie können es auch dann verwenden, wenn Sie kein Django sind. Versuchen Sie es also bitte. Wenn Sie andere empfohlene Tools zur automatischen Dokumenterstellung haben, würde ich mich freuen, wenn Sie einen Kommentar abgeben könnten.

Danke fürs Lesen.