Blog // Exirel.me

Retrouvez tous les articles liés au tag autodoc 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.

Documenter ses applications

Par Florian Strzelecki - 19:18 - 23.11.2009

Tags : Python, Documentation, Programmation, Bonne pratique, Technique, autodoc

Le pouvoir de la documentation est immense, et mésestimé par beaucoup trop de monde, parfois même par ceux à qui elle serait le plus utile, les développeurs.

Une documentation peut faire gagner du temps aux développeurs, mais c'est bien plus que ça. Le fait de documenter ses applications va au-delà du fait de gagner du temps, ou de gagner en compréhension : c'est un signe de qualité.

Pour ma part, je considère que documenter mes applications est un devoir, et un gage de qualité. Avec une bonne documentation, je montre que mon application a été pensée et imaginée dans le bon sens.

Une bonne documentation, évidement, car une mauvaise est peut-être pire que tout finalement.

La documentation de Django

Image : La documentation de Django