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 fichierREADME à 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 exemplereStructuredText 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 fichierINSTALL est moins nécessaire avec Python. Les instructions d’installation sont souvent réduites à une commande, commepipinstallmodule oupythonsetup.pyinstall et ajoutée au fichierREADME.
Un fichierLICENSE devraittoujours être présent et préciser la licence sous laquelle le logiciel est mis à la disposition du public.
Un fichierTODO file ou une sectionTODO dans leREADME devrait lister le développement prévu pour le code.
Un fichierCHANGELOG ou une section dans dans leREADME 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:
Uneintroduction 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.
Untutoriel 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.
Uneréférence d’API est généralement générée à partir du code (voirdocstrings). 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 markupreStructuredText 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ébergementgénial etgratuit pour votre documentationSphinx: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 avecSphinx et est hébergé surRead The Docs
reStructuredText¶
La plupart de la documentation Python est écrite avecreStructuredText. C’est comme le Markdown avec toutes les extensions optionnelles intégrées.
LereStructuredText Primer et lereStructuredText 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, lesdocstrings décrivent les modules, les classes et les fonctions:
defsquare_and_rooter(x):"""Returns the square root of self times self."""...
En général, suivez la section des commentaires de laPEP 8#comments (le “guide de style Python”). Plus d’informations sur les docstrings peuvent être trouvées sur laPEP 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 lefonctionnement de la fonction ou de la classe:
# This function slows down program execution for some reason.defsquare_and_rooter(x):"""Returns the square root of self times self."""...
Autres outils¶
Vous pouvez voir ceux-là dans la nature. UtilisezSphinx.
- Pycco
Pycco est un “générateur de documentation basé sur un style de Programmation lettrée” et est un port deDocco 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.
