Nouveau code.spip.net

Dev
#1

Bonjour à toutes et tous,

Et belle année à vous, pour autant qu’elle puisse l’être.

J’ai pris un peu de temps pour mettre à jour les documentations du code PHP de SPIP et des plugins (code.spip.net et anciennement code.plugins.spip.net). Le nouveau site utilise phpDocumentor 3.x.

Précédemment, ceux-ci étaient réalisés avec une version 2.x de phpDocumentor et des « templates » (twig) entièrement sur mesure. Cependant plusieurs éléments faisaient que ces documentations n’étaient plus adaptées :

  • déjà à l’époque sur mes templates il manquait les Traits, et certains autres éléments de PHP,
  • la syntaxe PHP évolue rapidement aussi avec plein de nouvelles écritures en php 8+
  • phpDocumentor est passé en version 3 totalement réécrit (depuis un bon moment)
  • il aurait fallu beaucoup de temps à maintenir et faire évoluer cela

Pour ces différentes raisons, j’ai migré vers les templates par défaut de phpDocumentor en version 3.x. J’ai juste surchargé certains éléments pour avoir notre entête SPIP (topnav et header), avec quelques adaptations CSS sur les couleurs. De la sorte, ça va simplifier grandement la maintenance, mais en contrepartie, on perd les pages qui avaient été écrites spécifiquement tel que la liste des « Balises » ou des « Pipelines ».

Enfin, il y avait un site SPIP sur https://code.spip.net qui disparait. Les quelques articles qui étaient éventuellement encore pertinents ont été déplacés sur le site Programmer. https://code.spip.net est maintenant un site statique entièrement généré par l’outil Autodoc

En dehors de « spip », les documentations générées sont toujours issues de la liste autodoc.txt et sont triées par organisations sur le git de SPIP (Core, Plugins, Squelettes, Outils). Si on ne connait pas l’organisation (dépot git externe par exemple), ça sera mis dans « Autres ».

Par ailleurs, s’il existe un fichier docs/index.rst ou doc/index.rst dans la source documentée, alors cette documentation sera aussi générée, et sa table des matières sera visible en colonne (entre les Links et les Packages ou Namespaces). Il n’y a encore aucun exemple dans les plugins SPIP, mais peut être que ça intéressera des personnes.

Note: il y a actuellement un petit bug sur la version 3.3.0 de phpDocumentor utilisée actuellement qui fait que certains fichiers de SPIP et ses plugins ne sont pas traités (dès lors qu’on déclare un define dans une fonction php — ce qui n’est ni une pratique courante, ni recommandée… mais bien présente chez nous). Ce sera corrigé dans la prochaine version de phpDocumentor.

7 « J'aime »
#2

Merci beaucoup pour le temps donné sur ce chantier ! Comme je le disais déjà sur IRC, c’est très classe :slight_smile:

C’est vraiment important et ça amha justifie la perte de quelques articles qui pourront être déplacer sur programmer.spip, bref, c’est top :*

#3

Merci, c’est top !

Les liens qui menaient directement vers les fichiers sur git.spip.net étaient assez pratiques, c’est envisageable de les remettre, ou trop compliqué/impossible ? Pas tout de suite hein, je demande juste d’un point de vue technique.

#4

Merci beaucoup !
je partage l’avis de tcharlss, le liens vers le code source de la fonction était très pratique. c’était une bonne porte d’entrée dans le code source de SPIP.
Mais rien de pressé :wink:

#5

J’ai amélioré quelques éléments. Et notamment tu as un lien vers la source.
Du moins du moment que c’est le même chemin que gitea / github…

1 « J'aime »
#6

En haut à droite donc des éléments

Capture d’écran 2022-01-08 à 21.36.17
Capture d’écran 2022-01-08 à 21.36.172026×388 32.3 KB

#7

Merci tu es au TOP !

#8

Hello,

La Boussole actuelle propose deux liens vers le code de spip et celui des plugins:

  • SPIP Code dans le menu Documentation
  • Code des Plugins dans le menu Contributions

Le refactoring de Matthieu fait que toute la documentation est accessible au travers d’un seul lien. Il faut donc revoir la stratégie de la Boussole.
Nous avons à mon avis plusieurs solutions:

  • Laisser la boussole telle qu’elle est actuellement en pointant vers le même lien.
  • Supprimer le lien Code des plugins uniquement et ne rien faire d’autre
  • Supprimer le lien Code des plugins et se poser la question du nom et du menu d’accueil du lien.

Vos avis ?

#9

Je dirais cela.

1 « J'aime »
#10

Dès lors qu’un plugin a un phpdoc assez complet, on peut le déclarer pour code.spip ou bien il y a d’autres conditions ou critères ?

#11

Tu publies dès que tu as un PHPDoc qui tient la route.

#12

Bonjour,
Je rencontre quelques difficultés depuis ce renouveau du site :

  1. des liens morts sur spip.net : par ex sur cette page où le lien vers la fonction bouton_action ( « Voir aussi » en bas de page ) envoie vers une 404.
  2. comment je fais pour changer de branche facilement et chercher une fonction dépréciée en SPIP 4 ? Je dois avoir les yeux brouillés, mais je n’ai pas vu / compris comment m’y prendre ^^

Ceci dit, le site a pris un joli coup de neuf : merci Matthieu !

#13

Bien vu, j’allais corriger le lien, mais je vois que la fonction bouton_action() citée dans le uses ici SPIP ne comporte pas de lien, et aucune trace de cette fonction dans le package SPIP :\

#14

Alors ce n’était déjà pas le cas dans la version précédente du site. Est-ce réellement un problème ?
Il faudrait mettre plusieurs versions de SPIP ? (et du coup quid des plugins-dist ?)

#15

bouton_action() est dans inc/filtres.php qui fait partie des fichiers non généré actuellement dans cette doc à cause du bug de phpDocumentor que je signalais en note dans le premier message.

#16

ha ok, on verra bien si une mise à jour future corrigera ça , merci pour l’info :slight_smile: