Blog // Exirel.me

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.

Doxygen, JavaDoc, phpDocumentor, etc.

Un bref aperçu pour ceux qui ne connaîtraient pas :

La documentation peut être utilisée directement, elle peut être partagée, ou déployer un ligne sur un serveur de fichiers statiques. De leurs côtés, JavaDoc et phpDocumentor appliquent les mêmes principes avec des approches et applications différentes. Il existe d'autres outils, pour d'autres langages et technologies, mais le concept reste le même.

Les trois sont plutôt similaires dans leurs approches et leurs fonctionnements, et leurs différences sont moins importantes pour la suite que leur similarité de fonctionnement.

Tout se base sur le code source.

Leurs forces et faiblesses proviennent tous de leur spécificité très forte : tout est généré à partir du code source. Que ce soit le contenu ou la structure de la doc générée, tout se base sur le code source.

Les avantages sont nombreux :

Ces avantages sont parfaits pour la documentation d'une interface, d'une bibliothèque, ou d'un langage, de par les aspects exhaustif et précis d'une référence technique. Cependant, ils peuvent devenir des inconvénients pour la documentation d'une application :

Il suffit de comparer cette documentation avec un boîte de Lego : une doc auto-générée indiquera le fonctionnement et les caractéristiques de chaque brique de Lego, mais elle ne permettra pas de fabriquer un ensemble cohérent. Pour cela, il faudra une documentation d'un autre niveau : la notice de montage.

« le tout possède parfois davantage de possibilités que la seule somme de ses parties »

Wikipédia

Dans le cadre d'une application, il faudra une documentation fonctionnelle, des manuels utilisateurs, une documentation d'installation, etc. ce qui nécessite d'autres outils.

Sphinx

Là où Doxygen (et les autres) n'utilise que le code source pour générer la documentation, Sphinx génère une documentation à partir de fichier reStructuredText, qui peuvent être pré-générés, ou créés intégralement à la main par l'auteur :

Je pense qu'un exemple de fichier .rst sera plus parlant :

Function :func:`func_name` can be referenced when needed, even when
using the ``autofunction`` directive.

.. autofunction:: module.path.func_name

Another text that will be displayed after the function's documentation.

Ceci génèrera un fichier HTML qui contiendra à la fois le texte avant et après que la documentation de la fonction, générée à partir du code source (signature & docstring).

Les auteurs, avec sphinx, disposent de plus de contrôle sur la structure :

Par exemple, dans un chapitre dédié à la gestion des données, l'auteur pourra insérer des liens automatiques vers les fonctions de traitement de ces données. Cependant, si une nouvelle fonction de traitement est ajoutée dans le code source, alors il faudra la référencer manuellement pour auto-documentation dans les fichiers .rst.

Ce que veulent les documentations

Si Sphinx donne la priorité à la documentation fonctionnelle de part la liberté de structure, les outils précédents donnent la priorité à la documentation technique de référence, de part la structure strictement liée au code source.

Typiquement, pour documenter une application :

Alors que pour fournir une référence exhaustive d'une bibliothèque :

Autant de contraintes qui ne répondent pas aux mêmes besoins font qu'un outil comme Doxygen est très performant dans sa tâche : limitée, mais spécifique et précise. Quant à Sphinx, il est très performant pour des documentations à plus large spectre.

Structure du code vs hiérarchie du contenu

Malheureusement, la force de Sphinx en fait aussi l'une de ses faiblesses pour intégrer l'autodoc : les risques d'oublier une fonction ou un module à auto-documenter sont plus grand, reposant trop souvent sur une intervention manuelle décorrélée du code source.

Sphinx donne la priorité à la hiérarchie du contenu plutôt qu'à la structure du code source.

De la même façon, Sphinx structure son contenu sur une hiérarchie qui n'est pas celle du code source, avec ou sans autodoc. On peut d'ailleurs le constater avec la documentation officielle de Python, où certains problèmes de structuration du contenu (entre autre chose) ont été pointés par cet article de 2013.

L'article en question pointe notamment du doigt la documentation du module os.path : vous pourrez remarquer que le menu ne permet pas de naviguer directement à la fonction de son choix. Ce problème vient du fonctionnement de Sphinx, qui donne la priorité à la hiérarchie du contenu plutôt qu'à la structure du code source, et ne dispose donc pas d'outil pour mettre en avant la hiérarchie du code source.

Pour donner un élément de comparaison, j'invite à lire le sommaire de la documentation PHP des fonctions sur les systèmes de fichier : on peut voir ici une structure qui reflète la structure du code source. Cela en fait une référence technique très facile à parcourir et à scanner visuellement.

Limites

Après des années d'utilisation de Sphinx, je suis confronté à ses limites. Le problème pour moi est dans l'outillage à ma disposition, et il n'est, en aucun cas, dans la comparaison des performances des différents type de documentation - toutes sont nécessaires, à différent degrés.

Ce dont j'aurais besoin aujourd'hui, c'est d'un outil qui me permette :

Il y a sans doute des choses que je pourrais coder moi même, à ce titre, je pense à deux extensions à ajouter à Sphinx :

Des idées ?

Du temps et de la motivation : ce sont les ressources dont je manque le plus (l'absence de motivation ayant souvent un impact des plus négatifs sur le temps disponible).

Si je pense avoir bien pris la mesure des limitations de Sphinx, je doute d'avoir fait plus que toucher du doigt les possibilités pour améliorer la situation.

Il me faudrait confronter mes idées et mon point de vue avec d'autres personnes, et peut-être qu'alors j'arriverais à faire progresser la question un peu plus loin qu'un article sur un petit blog personnel.

Des idées ?

Notes & Ajouts

À noter l'existence de autosummary pour Sphinx, qui pourrait presque servir à générer un sommaire. Malheureusement, il souffre du même défaut que le reste : il faut maintenir son contenu à la main, et la sortie n'est pas forcément ce à quoi on s'attend. Et surtout, ce n'est pas utilisé par défaut par sphinx-autogen...