Une bonne partie de l’application Autodoc disparait pour plusieurs raisons :
- On cherche à simplifier la maintenance de cette doc en ne créant pas de thème personnalisé,
car effectivement, la syntaxe PHP évolue bien plus vite que le temps disponible
pour adapter les templates aux évolutions. On préfère user juste d’un peu de
cosmétique avec un peu de CSS. Le thème complet d’avant disparait.
- L’application est devenue un .phar et les surcharges sont improbables là où le code
d’origine ne l’a pas explicitement prévu. Je n’ai absolument pas l’énergie
de me replonger à gérer des passes de compilation comme avant pour retrouver
les balises ou pipelines dans le code (je ne sais même pas si c’est faisable sur cette version).
Cette partie disparait aussi.
- On bascule sur du PHP 8.0 minimum.
On s’appuie sur différentes librairies dont toujours symfony/console, mais aussi
symfony/filesystem et League/Pipeline.
On gère les téléchargements et mises à jour Git avec l’outil checkout
(qui est donc nécessaire). Le fichier phpDocumentor.phar est aussi nécessaire
dans le répertoire de travail, tout comme la création d’un répertoire `var`
écrivable.
Une décoration spécifique du thème par défaut (css, svg), est copiée
dans la config générée (var/config/templates), et est alors utilisée
par phpDocumentor (sur le même principe de surcharge que les squelettes SPIP)
Les commandes from:directory, from:git, from:plugin, from:spip sont adaptées.
La commande from:file (lecture d’un fichier archivelist.txt) reste à faire.
Nombreuses adaptations :
1) les binaires sont maintenant sans extension .php
2) Pour tenir compte des <options> que l'ont passait dans phpdoc.xml, spécifique à l'autodoc,
il faut grandement ruser maintenant car le sérialiseur / désérialiseur utilisé maintenant par phpdocumentor
ne conserve que les éléments qui lui sont déclarés. Pour cela, on surcharge donc la classe Configuration
de phpdocumentor pour ajouter notre tableau d'options.
À noter que la syntaxe est légèrement différente (voir Helpers/phpdoc_helper.xml)
3) Pour faire parvenir les données de configuration au template Twig, et suite toujours au
changement dans la gestion de la configuration de phpdocumentor, on transmet directement
aux template la configuration connue (sans la recalculer). Mais pour cela, on doit
surcharger le Writer/Twig pour ajouter notre élément. La surcharge est minime heureusement.
4) L'autoloader est déclaré différemment également. Il est appelé avant le chargement de phpDocumentor
et lui est transmis lors de la création (new Application(...)). On s'adapte (dans bin/autodoc) et on
adapte toutes les commandes Helpers pour transmettre cet autoloader… Pfiou.
Du coup, pour simplifier un peu, on crée une Application pour le Helpers, et on déporte
de bin/autodoc_helper vers l'application la déclaration des commandes utilisables.
On indique à composer qu'on a nos classes suivent PSR-0 pour passer dans l'autoload.
Pour l'instant… ça ne fait rien de plus que faire fonctionner phpDocumentor normalement.
Matthieu Marcillaud
marcimat@rezo.net