Deux outils de génération de documents que vous souhaitez absolument utiliser si vous écrivez python

Cela me convient, qui étudie sérieusement le python et le django depuis 3 mois! !! !! Voici deux outils de génération de documents auxquels j'ai pensé! Le contour de chaque outil est décrit dans l'ordre de la méthode d'application dans django.

Il est souvent recherché et répertorié en haut, mais j'espère que vous pourrez vous y référer comme exemple d'application dans django.

Documentation Docstring utilisant Sphinx

Sphinx est un outil qui facilite la création de documents intelligents et beaux. Développé par Georg Brandl et publié sous licence BSD. Créé à l'origine pour la documentation Python, cet outil est maintenant utilisé comme un outil pour faciliter la documentation de projets dans un large éventail de langages. (par Site officiel)

J'ai découvert Read the docs, un service d'hébergement de documents pour la communauté open source. Au fait, il semble que ce service soit également fait par Django.

• Lire la documentation officielle
• Exemple de notebook Jupyter

Sphinx nécessite l'utilisation d'un balisage appelé reStructuredText, mais la commande sphinx-apidoc peut générer automatiquement la première source. Le texte original à convertir en premier utilise docstring. Il semble que sphinx.ext.autodoc décrit dans conf.py du fichier de configuration sphinx recherchera la docstring dans le répertoire d'origine. En d'autres termes python docstring -> rst -> html Cela signifie que le sphinx fera toute la conversion pour vous! Un immense merci! !!

Procédure de création

Créons tout de suite un document pour le projet django!

• Il est nécessaire d'écrire la docstring dans le projet python à l'avance. Quel est le docstring sorti plus tôt? Cet article est recommandé pour ceux qui l'aiment → - Introduction à Google docstring

Exécutez la commande suivante dans le terminal.

#Installation de la bibliothèque et du thème
pip install sphinx sphinx-rtd-theme
#Création de la destination de sortie du document
mkdir docs
#Créez le premier en spécifiant la racine du projet django
sphinx-apidoc -fF -o ./docs ./path/to/django_project_root
# change directory
cd docs
# conf.Ajustement de py(Le contenu est écrit séparément!)
vi conf.py
#création html
make html

• conf.py

Seule la partie supplémentaire est décrite. Veuillez vous référer à # --hogehoge -------- pour la position supplémentaire.

conf.py

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

#Spécifiez le chemin et les paramètres du projet django
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,support docstring de style numpy
]

language = 'ja' #Ai Amu Japon

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

html_theme = 'sphinx_rtd_theme' #Spécifiez l'apparence de Lire les documents

C'est juste généré automatiquement, mais c'est assez complet! Cet article a été utile pour ceux qui veulent organiser la sortie automatique d'abord → study sphinx J'ai également modifié en partie parce que la destination du lien décrite dans le premier était en conflit avec le nom du répertoire utilisé dans le projet django (・ _ ・)

Rapport de couverture utilisant la couverture

Vient ensuite la génération de rapports de couverture! Cliquez ici pour l'image complète → [https://nedbatchelder.com/files/sample_coverage_html/index.html) Il y a deux outils à utiliser, pytest et couverture!

Officiel: pytest

pytest est un outil de test Python mature et complet qui vous aide à écrire de meilleurs programmes. Le framework pytest facilite l'écriture de petits tests, mais il peut être étendu pour prendre en charge des tests fonctionnels complexes d'applications et de bibliothèques. (par officiel)

C'est l'un des frameworks de test de python. Il existe un cadre de test appelé unittest, qui est standard pour python, mais je préfère personnellement pytest car l'opérateur de comparaison est plus facile à écrire intuitivement.

Officiel: couverture

Coverage.py est un outil pour mesurer la couverture de code des programmes Python. Surveillez le programme, enregistrez quelle partie du code a été exécutée et analysez la source pour identifier le code qui aurait pu être exécuté mais pas. Les mesures de couverture sont généralement utilisées pour évaluer l'efficacité d'un test. Vous pouvez montrer quelles parties du code sont exécutées par le test et lesquelles ne le sont pas. (Par officiel)

Cela permet de vérifier l'exhaustivité du code testé. Si vous le réglez à 100%, vous serez satisfait, mais soyez prudent car il reste encore des choses à vérifier.

L'une des fonctions de la couverture est la fonction de sortie du rapport html.

--Facile à comprendre la partie testée

• Vous pouvez réduire les problèmes de création de documents

Et deux oiseaux avec une pierre! Veuillez l'utiliser!

Procédure de création

Maintenant, définissons pytest et la couverture dans le projet Django et produisons le rapport!

Exécutez la commande suivante dans le terminal.

#Installer la bibliothèque
pip install pytest-django coverage
# change directory(répertoire du projet django)
cd django_project_path
# pytest.ajustement ini(Le contenu est écrit séparément!)
vi pytest.ini
# p.Ajustement de coveragerc(Le contenu est écrit séparément!)
vi .coveragerc
#Obtenez une couverture
coverage run -m pytest
#Vérifier le rapport de couverture
coverage report -m
#Sortie de la couverture html
coverage html

• pytest.ini

Cette fois, je l'ai réglé sur le réglage minimum. Le [pytest-django] officiel (https://pytest-django.readthedocs.io/en/latest/tutorial.html) est également petit et facile à comprendre, veuillez donc le vérifier.

pytest.ini

[pytest]
addopts = --ds=config.settings #Spécifier les paramètres de Django
python_files = tests.py test_*.py #Spécifiez le code de test

• .coveragerc

Un fichier qui définit les options d'exécution, de rapport et html pour la commande de couverture. Ici aussi, l'explication des options de la [couverture] officielle (https://coverage.readthedocs.io/en/coverage-5.2.1/config.html) est facile à comprendre avec une petite quantité. En plus de la sortie html, la sortie xml et json est également possible.

.coveragerc

[run]
source=. #Spécifier la racine du projet django
omit= */migrations/*　#Décrivez les fichiers et répertoires que vous souhaitez exclure
      */tests/*
      */htmlcov/*
[report]
omit= */migrations/*
      */tests/*
[html]
directory = htmlcov #Sortie html dans un répertoire appelé htmlcov

• Si vous voulez obtenir une couverture html, exécutez pip install django-coverage-plugin et ajoutez ce qui suit.

.coveragerc

[run]
plugins =
    django_coverage_plugin

Référence: Django memo (26): Mesurer la couverture avec coverage.py

C'est également une opération simple et des documents faciles à lire peuvent être générés automatiquement! Lors de l'utilisation d'une commande, il est facile de vérifier les numéros de ligne qui ne sont pas couverts par coverage report -m, ou d'afficher les détails du test avec pytest -v.

finalement

Vous pouvez créer un document avec moins d'effort, donc si vous êtes autorisé à l'utiliser, votre efficacité au travail s'améliorera. Cette fois, j'ai pris django comme exemple, mais vous pouvez l'utiliser même si vous n'êtes pas django, alors essayez-le. Si vous avez d'autres outils de création automatique de documents recommandés, je vous serais reconnaissant de bien vouloir commenter.

Merci pour la lecture.