Blog // Exirel.me

Retrouvez tous les articles liés au tag sphinx via le flux rss dédié à ce tag.

Limites de sphinx-autodoc

Par Florian Strzelecki - 17:31 - 09.07.2017

Tags : Python, Documentation, sphinx, autodoc

J'utilise Sphinx pour écrire des documentations depuis quelques années maintenant, que ce soit pour des projets Python ou non, et avec le recul j'en viens à en considérer les limites. Elles sont nombreuses, et de plus en plus frustrantes.

Mais pour le moment, je vais me concentrer sur son extension autodoc, qui inspecte le code et permet d'en extraire les docstring. Son but est simple : générer une documentation exhaustive et à jour (ce que j'appelle "la référence technique"), puisqu'elle concorde avec le code source documenté (pour l'exercice, on supposera toujours vrai que les docstrings soient toujours à jour avec le code source).

Ma première expérience de documentation fut avec Doxygen, à l'IUT (entre 2004 et 2006). Ce fut une bonne expérience, et une ouverture sur la documentation et sur son importance pour la qualité.

Sans expérience en la matière, il m'apparut très vite comme une pratique essentielle du métier, bien que ce ne soit pas l'avis de tout le monde. Autant dire qu'il y a de quoi écrire des livres entiers sur la place de la documentation, que ce soit dans notre culture ou dans nos passages à la pratique.

Plus tard, j'ai été amené à utiliser des outils similaires, pour d'autres langages, et pour un lectorat de plus en plus varié. Depuis, j'ai même eu l'occasion de donner plusieurs ateliers et conférences sur le sujet, qui me passionne peut-être même plus que le code lui même.