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

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.

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!

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

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!

pytest 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.

coverage 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

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

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

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

.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.

Recommended Posts

Deux outils de génération de documents que vous souhaitez absolument utiliser si vous écrivez python
N'écrivez pas Python si vous voulez l'accélérer avec Python
Si vous souhaitez compter les mots en Python, il est pratique d'utiliser Counter.
Comment écrire des variables d'environnement que vous ne voulez pas mettre sur [GitHub] Python
Si vous voulez créer un bot discord avec python, utilisons un framework
Si vous souhaitez utiliser Cython, incluez également python-dev
[Python] Si vous souhaitez soudainement créer un formulaire de demande
Si vous souhaitez que vos collègues utilisent la même langue
Je souhaite utiliser un caractère générique que je souhaite décortiquer avec Python remove
Je veux savoir si vous installez Python sur Mac ・ Iroha
[Python] Lorsque vous souhaitez utiliser toutes les variables dans un autre fichier
Si vous souhaitez affecter une exportation csv à une variable en python
Indispensable si vous utilisez Python! Comment utiliser Numpy pour accélérer les calculs!
Si vous écrivez un test piloté par table go en python, il peut être préférable d'utiliser subTest
[Python] Utilisez des pandas pour extraire △△ qui maximise ○○
Comment écrire des commentaires de document Python (Docstrings)
Que faire si vous ne pouvez pas utiliser la recherche de grille de sklearn en Python
Si vous souhaitez inclure awsebcli dans CircleCI, spécifiez la version de python
Si vous souhaitez utiliser NumPy, Pandas, Matplotlib, IPython, SciPy sous Windows
Je veux utiliser jar de python
[Python] Si vous souhaitez dessiner un diagramme de dispersion de plusieurs clusters
Si vous souhaitez créer une application Windows (exe) qui peut être utilisée maintenant en utilisant uniquement Python
Comment créer un environnement lorsque vous souhaitez utiliser python2.7 après l'installation d'Anaconda3
Si vous souhaitez créer une application TODO (distribuée) maintenant en utilisant uniquement Python
Utilisez PIL en Python pour extraire uniquement les données souhaitées d'Exif
Créer un outil de génération de documents Python car il est difficile d'utiliser sphinx
[Python] Comment utiliser deux types de type ()
Je veux utiliser MATLAB feval avec python
Si vous souhaitez créer Word Cloud.
Je souhaite utiliser le répertoire temporaire avec Python2
Je veux utiliser le solveur ceres de python
Je veux écrire dans un fichier avec Python
Vous devez savoir si vous utilisez Python! 10 bibliothèques utiles
Voulez-vous que je corrige cette copie?
Un mémo de fonction utile lorsque vous souhaitez entrer dans le débogueur si une erreur se produit lorsque vous exécutez un script Python.
Comment installer et utiliser pyenv, que faire si vous ne pouvez pas changer de version de Python
Que faire si vous ne souhaitez pas utiliser de noms de colonnes japonais lors de l'utilisation d'ortoolpy.logistics_network
Je veux écrire en Python! (1) Vérification du format de code
Je veux écrire en Python! (2) Écrivons un test
[Python] Comment écrire une docstring conforme à PEP8
Je veux écrire en Python! (3) Utiliser des simulacres
Pour ceux qui veulent écrire Python avec vim
Notes de site pour vous aider à utiliser NetworkX avec Python
Le langage de programmation que vous souhaitez pouvoir utiliser
Je veux utiliser le jeu de données R avec python
Je connais? Analyse de données à l'aide de Python ou de choses que vous souhaitez utiliser quand vous le souhaitez avec numpy
[Python3] Code qui peut être utilisé lorsque vous souhaitez redimensionner des images dossier par dossier
[Python] Lorsque vous souhaitez importer et utiliser votre propre package dans le répertoire supérieur
Si vous ne pouvez pas utiliser Beautiful Soup 4 après la mise à jour vers Python 3.5. ImportError: aucun module nommé bs4
[Django] Mémorandum lorsque vous souhaitez communiquer de manière asynchrone [Python3]
Je veux initialiser si la valeur est vide (python)
[Introduction à Python] Comment écrire des branches conditionnelles en utilisant des instructions if
Utilisez des cas qui vous motivent à utiliser Docker que vous n'avez jamais utilisé
Si vous écrivez TinderBot en Python, elle peut le faire
[Python] Comment écrire une instruction if en une phrase.
Utiliser Azure ML Python SDK 4: écrire la sortie dans le stockage Blob - partie 2
Utilisez aggdraw lorsque vous voulez dessiner magnifiquement avec un oreiller
[Route vers Python intermédiaire] Utiliser l'instruction if dans la notation d'inclusion de liste