Documentation¶
La lisibilité est une priorité pour les développeurs Python, à la fois dans la documentation du projet et du code. Suivre quelques bonnes pratiques simples peut vous sauver, vous et d’autres, beaucoup de temps.
Documentation de projet¶
Un fichier README à la racine du répertoire devrait donner des informations générales à la fois pour les utilisateurs et les mainteneurs d’un projet. Il devrait être du texte brut ou écrit dans avec un markup très facile à lire, par exemple reStructuredText ou Markdown. Il devrait contenir quelques lignes expliquant le but du projet ou de la bibliothèque (sans supposer que l’utilisateur ne sait rien sur le projet), l’URL de la source principale du logiciel, ainsi que des informations de crédit basiques. Ce fichier est le principal point pour les lecteurs du code.
Un fichier INSTALL est moins nécessaire avec Python. Les instructions d’installation sont souvent réduites à une commande, comme pip install module ou python setup.py install et ajoutée au fichier README.
Un fichier LICENSE devrait toujours être présent et préciser la licence sous laquelle le logiciel est mis à la disposition du public.
Un fichier TODO file ou une section TODO dans le README devrait lister le développement prévu pour le code.
Un fichier CHANGELOG ou une section dans dans le README doit compiler un bref aperçu des changements dans la base de code pour les versions les plus récentes.
Publication de projet¶
Selon le projet, la documentation peut inclure tout ou partie des composants suivants:
Une introduction devrait montrer une très bref aperçu de ce qui peut être fait avec le produit, en utilisant un ou deux cas d’utilisation extrêmement simplifiés. C’est le pitch de 30 seconds de votre projet.
Un tutoriel devrait montrer certains cas d’utilisation de base plus en détail. Le lecteur suivra une procédure pas à pas pour configurer un prototype fonctionnel.
Une référence d’API est généralement générée à partir du code (voir docstrings). Elle liste toutes les interfaces, les paramètres et les valeurs de retour publiques.
La documentation développeur est destinée aux contributeurs potentiels. Cela peut inclure les conventions de code et la stratégie de conception générale du projet.
Sphinx¶
Sphinx est de loin l’outil le plus populaire de la documentation Python. Utilisez-le Il convertit le langage de markup reStructuredText dans une gamme de formats de sortie incluant HTML, LaTeX (pour les versions imprimables PDF), les pages de manuel et le texte brut.
Il y a aussi un hébergement génial et gratuit pour votre documentation Sphinx: Read The Docs. Utilisez-le. Vous pouvez le configurer avec des hooks de commit liés à votre dépôt source. Ainsi, la re-génération de votre documentation se fera automatiquement.
Note
Sphinx est célèbre pour sa production d’API, mais il fonctionne aussi bien pour la documentation générale de projet. Ce guide est construit avec Sphinx et est hébergé sur Read The Docs
reStructuredText¶
La plupart de la documentation Python est écrite avec reStructuredText. C’est comme le Markdown avec toutes les extensions optionnelles intégrées.
Le reStructuredText Primer et le reStructuredText Quick Reference devraient vous aider à vous familiariser avec sa syntaxe.
Conseils de documentation de code¶
Les commentaires clarifient le code et ils sont ajoutés dans le but de rendre le code plus facile à comprendre. En Python, les commentaires commencent par un dièse (signe dièse)(#).
En Python, les docstrings décrivent les modules, les classes et les fonctions:
def square_and_rooter(x):
"""Returns the square root of self times self."""
...
En général, suivez la section des commentaires de la PEP 8#comments (le “guide de style Python”). Plus d’informations sur les docstrings peuvent être trouvées sur la PEP 0257#specification (Le guide convention Docstring).
Commenter des section de code¶
N’utilisez pas des chaînes avec triple-guillemets pour commenter le code. Ce n’est pas une bonne pratique, parce que les outils orientés lignes en ligne de commande tels que grep ne seront pas conscients que le code commenté est inactif. Il est préférable d’ajouter des dièses au niveau d’indentation correct pour chaque ligne commentée. Votre éditeur a probablement la capacité à faire cela facilement, et cela vaut la peine d’apprendre le bouton pour commenter/décommenter.
Docstrings et la magie¶
Certains outils utilisent docstrings pour intégrer un comportement étant plus que de la documentation, tels que la logique de test unitaire. Ceux-ci peuvent être bien, mais vous ne vous tromperez jamais avec “voici ce que cela fait.”
Docstrings versus commentaires de bloc¶
Ceux-ci ne sont pas interchangeables. Pour une fonction ou une classe, le premier bloc de commentaire est une note d’un programmeur. Le docstring décrit le fonctionnement de la fonction ou de la classe:
# This function slows down program execution for some reason.
def square_and_rooter(x):
"""Returns the square root of self times self."""
...
Autres outils¶
Vous pouvez voir ceux-là dans la nature. Utilisez Sphinx.
- Pycco
Pycco est un “générateur de documentation basé sur un style de Programmation lettrée” et est un port de Docco en node.js. Il transforme le code en un rendu HTML avec code et documentation côte à côte.
- Ronn
Ronn génère les manuels Unix. Il convertit des fichiers texte lisibles par l’homme en roff pour affichage dans le terminal, et également en format HTML pour le web.
- MkDocs
MkDocs est un générateur de site statique simple et rapide qui est orientée vers la construction de la documentation de projet avec Markdown.
