Yop,
Comme le dit brillamment Suske, il y a effectivement des travaux engagés autour de la documentation du code source de SPIP.
Il y a 2 projets lancés il me semble
- autodoc : qui est une visualisation de la documentation du code source de SPIP (ou de plugins pour SPIP). Documentation effectuée au format PHPDoc.
- APIs : qui est l'idée de regrouper sur un site une documentation des APIs (et pas uniquement extraites du code source, mais avec des articles associés), et d'avoir des commentaires possibles sur les éléments, un peu à la php.net. Un peu comme l'était doc.spip.org, mais uniquement pour les fonctions d'api. (plus d'infos là http://blog.smellup.net/spip.php?article59 – mais autodoc ne passe plus par une BDD en SPIP contrairement au moment de la rédaction de l'article).
Pour ma part, je teste depuis quelques temps l'utilisation de phpDoc au sein du code source de SPIP. Cela m'a permis d'apprendre comment il s'écrit et comment on peut ensuite l'utiliser.
Le logiciel phpDocumentor sur lequel je me base permet d'extraire toute la documentation d'un code source PHP et de le compléter au besoin, puis d'en générer un site. J'avais testé les vues fournies par défaut avec phpDocumentor, mais elles sont plutôt prévues pour un code PHP basé sur une architecture avec namespace et classes, ce que l'on n'a pas vraiment, et par ailleurs, cela ne permet pas de mettre en avant quelques spécificités de SPIP.
J'ai donc créé un plugin pour phpDocumentor & Twig pour avoir un affichage différent. C'est ce qu'on voit actuellement sur http://autodoc.magraine.net/spip-dev/zora/index.html , capable d'isoler les balises, filtres, critères qui sont déclarés à SPIP, et d'autres choses. C'est ce plugin (et templates en Twig) qui est nommé Zora, mais peut importe.
Il me semble qu'on arrive maintenant, sur cet espace de développement (autodoc) à quelque chose de présentable et d'utilisable effectivement.
En tout cas, il a le mérite d'avoir une documentation du code à jour, ce qui n'est malheureusement plus le cas de doc.spip.org. D'autre part, cela permet d'utiliser une nomenclature de documentation de code plus proche de ce qui se fait habituellement (l'usage de phpdoc) et sa généralisation dans le code source permettra toujours de générer des documentations automatiques nativement, par phpDocumentor ou d'autres (même si elles n'auront pas les spécificités qu'apportent le plugin Zora).
Je présenterai un jour prochain dans un autre mail quelques spécificités de l'écriture de phpDoc, que j'ai pu voir du coup en en écrivant quelques morceaux.
Ce qui peut être intéressant comme retours maintenant pour ceux qui suivent cette liste, c'est est-ce que http://autodoc.magraine.net/spip-dev/zora/index.html vous paraît clair et utilisable ?
Enfin sur la migration de doc.spip.org, il me semble qu'il y a plusieurs choses à faire avant son éventuelle disparition. En effet, ce site comporte 2 choses :
- des documentations (articles) sur certains sujets techniques qu'on ne retrouve pas pour l'instant ailleurs. Il faudrait les migrer quelque part. Ce peut être sur spip.net, sur programmer3.spip ou sur le futur site d'API.
- des descriptions de fonctions crées de façon "collaborative" avant que les crayons ne soient enlevés du site. Pour celles là, il faudrait soit les réinjecter si elles sont pertinentes dans le code source, soit trouver un refuge quelque part. Certaines avaient déjà été mises en partie dans programmer.spip d'ailleurs.
- peut être faire en sorte qu'un .htaccess puisse rediriger des @functions sur le nouveau site.
Enfin, concernant 'autodoc', zora et phpDocumentor, ils vont être amenés encore une fois à évoluer énormément. Peut être pas sur le résultat obtenu, mais sur leur code source, car phpDocumentor va une nouvelle fois modifier considérablement son fonctionnement avant de sortir officiellement sa version 2.0, ceci afin d'intégrer Twig et son système de template de façon optimale (c'est à dire non géré par un énorme fichier XML, mais par des objets php liés entre eux, bien plus facilement exploitables).
Je crois que j'ai tout dit pour ce soir.
Qu'en pensez vous ?
MM.
