pdoc – La documentation Python sans documentation
Vous avez déjà passé plus de temps à configurer Sphinx qu’à coder votre projet Python ? Bienvenue au club !
Et oui, paradoxalement, parfois documenter son code devient plus compliqué que d’écrire le code… Vous voulez juste afficher vos docstrings joliment, mais avant ça il faut vous taper 200 pages de doc, choisir parmi 47 thèmes, configurer des dizaines d’extensions et comprendre la syntaxe reStructuredText. Breeeef, la flemme !
Heureusement, il existe une alternative qui va vous réconcilier avec la documentation : pdoc.
pdoc, c’est un outil de documentation Python qui ne nécessite pas de documentation. Vous tapez simple pdoc votre_module et c’est tout. Pas de fichier de config interminable, pas de choix existentiels entre différents builders, pas de migration depuis votre version de Sphinx de 2018 qui refuse de compiler.
Ça génère directement une belle doc à partir de votre code existant !!
Si vous avez déjà écrit des docstrings propres et utilisé les type annotations de Python, vous avez déjà fait 100% du boulot car pdoc se contente de prendre ce qui existe et de l’afficher élégamment. Pas de traduction, pas de réécriture, pas de fichiers .rst à maintenir en parallèle de votre code.
Votre code EST la documentation et ça c’est beau !
L’outil comprend les docstrings au format numpydoc et Google-style, fait des liens automatiques entre les identifiants, respecte votre variable __all__ et génère du HTML standalone que vous pouvez héberger n’importe où. Il y a même un serveur web intégré avec live reload pour développer votre doc en temps réel.
Pour mettre ça en place, faut installer pdoc avec
pip install pdoc
Puis vous lancez
pdoc ./votre_projet.py
ou
pdoc nom_de_votre_module
Et c’est tout !
Bien sûr si vous bossez sur un gros projet avec des besoins spécifiques, des guides utilisateurs complexes, des dizaines de pages de tutoriels et une doc multilingue, Sphinx reste le roi, mais pour la grande majorité des projets Python, ceux qui ont juste besoin d’une doc API claire et lisible, pdoc fait ça comme un chef, sans que vous ayez besoin d’un doctorat en outil de documentation.
Bref, si vous en avez marre de passer plus de temps sur votre documentation que sur votre code, pdoc mérite le détour car documenter son code devrait être aussi simple que de le coder, non ?
Pour tester pdoc, direction
pdoc.dev
ou directement
le repo GitHub
.
Source : korben.info