Documentation des APIs de SPIP Une brique pour le chantier de refonte de la documentation

, par _Eric_

| 12 |

Génèse et renaissance

Il y a près de deux ans, au début de l’aventure SVP, nous échangions avec Denis sur l’extraordinaire efficacité d’un site comme PHP.net pour les développeurs PHP en quête d’une information rapide et précise sur une fonction PHP donnée. A cette époque, et c’est encore le cas actuellement, nous avions toujours une fenêtre ouverte pour consulter :

Nous étions donc arrivés à la conclusion qu’il serait bien utile de créer un site unique à la PHP.net pour SPIP qui regrouperait l’ensemble des « fonctions publiques » fournies par SPIP pour le développement des squelettes et des plugins. Mais les quelques réflexions et schémas de données esquissés à l’époque restèrent dans nos cartons...

Fin 2011, suite à une rencontre informelle avec Matthieu et Romy, j’ai relancé un peu cette idée comme un élément technique de la refonte de la documentation SPIP. Le thread est toujours consultable sur la liste spip-dev. Mais là encore, d’autres travaux ont relégué ces réflexions au second plan.

Et puis, il y a deux mois, c’est Matthieu qui a rallumé la flamme en nous proposant un « plan d’attaque » pour refondre doc.spip.org en utilisant PHPDocumentor 2, un outil destiné à générer une documentation des fichiers, fonctions, méthodes, classes, constantes... à partir du code de SPIP.

Deux expérimentations en cours

Ainsi, suite à la mise en place sur le serveur de Matthieu d’un environnement permettant de générer via PHPDocumentor un fichier XML à partir du code SPIP, nous avons commencé à conduire deux expérimentations parallèles, à savoir :

  • Autodoc, pour Matthieu,
  • APIS, de mon coté.

Etant donné que ces deux solutions conduisent à alimenter la base de données d’un site SPIP présentant la documentation du code, on discutera en fin d’article de l’intérêt à conserver l’une ou l’autre deux solutions.

Autodoc

Le principe d’Autodoc est de fournir un processus entièrement automatique de génération de site. En cela il se veut le successeur de Amemo qui alimente actuellement le site doc.spip.org. Comme APIS, Autodoc importe le PHPDoc dans une base de données afin d’utiliser les squelettes et boucles SPIP pour afficher les éléments de code. Le schéma de principe est le suivant :

Il est à noter que Autodoc n’autorise qu’un seul sens d’alimentation, à savoir, du code vers la base. La référence est donc le code.

APIS

Le principe d’APIS est assez proche si ce n’est qu’il donne la possibilité de rajouter manuellement des informations complémentaires comme des exemples voire de corriger les données importées du code si celles-ci sont erronées. Dans ce cas une option permet d’exporter les en-têtes PHPDoc modifiées et de les réinjecter manuellement dans le code. Le schéma de principe est illustré ci-dessous :

APIS permet également de synchroniser des modifications faites dans le code avec le contenu de la base de données en laissant le contrôle total au webmestre comme le font les outils de synchronisation des contacts, par exemple. Contrairement à Autodoc la référence n’est donc pas forcément le code.

Et maintenant ?

Les deux plugins, Autodoc et APIS, fonctionnent aujourd’hui suffisamment bien pour prouver l’intérêt des concepts mise en œuvre. Il reste néanmoins encore pas mal de travail pour les finaliser et les mettre en production.

Mais avant ça, il est nécessaire de s’interroger sur l’intérêt ou pas de conserver les deux approches - ce qui veut dire deux sites différents - ou de promouvoir l’une par rapport à l’autre voire de trouver une nouvelle voie.

A mon avis, rien n’empêche aujourd’hui de conserver les deux approches en rénovant le site « doc.spip.org » avec Autodoc et en créant un site « apis.spip.net » avec APIS. En effet, APIS a vocation à présenter une documentation complète sur les seules fonctions publiques de SPIP et sa mise au point prendra donc du temps.
D’un autre coté, Autodoc permet dès aujourd’hui de présenter toute la documentation du code de SPIP.

Par contre, je pense que la philosophie d’APIS est plus vertueuse à terme. En effet, SPIP en tant que framework doit clairement définir sa couche d’interface publique utilisable par les développeurs - de plugins ou squelettes - et rendre inaccessibles ses fonctions internes. En effet, rationnaliser, limiter et promouvoir cette seule couche publique doit permettre à terme d’assurer une meilleure compatibilité ascendante des versions SPIP et de diminuer la maintenance.