Écrire la documentation d’un plugin SPIP

Cet article (mis à jour le 7 mars 2021) explique en 4 étapes comment créer la documentation d’un plugin sur Contrib. Il s’adresse aussi aux administrateurs et administratrices de SPIP-contrib qui auraient des trous de mémoire ;)

Prérequis : vous disposez d’un plugin non documenté

Si vous souhaitez réaliser un plugin, ce n’est pas la bonne page ! Pour réaliser un plugin pour SPIP3, utilisez la fabrique qui permet d’automatiser la création de plugins La Fabrique et le site https://programmer.spip.net/-Developper-des-plugins- pour en savoir plus.

Les développements de SPIP et de ses contributions se font désormais sur https://git.spip.net
voir FAQ pratique : Comment SPIPer avec git.spip.net

1. Rédigez l’article de documentation

Résumé :
Inscrivez-vous sur SPIP Contrib, allez dans l’espace de rédaction pour rédiger l’article dont vous serez l’auteur ou l’autrice, enregistrez, ajoutez un logo pour illustrer l’article, des mots-clefs, puis cliquez sur demander la publication.

Voici une structure-type qui facilitera l’utilisation de l’article comme documentation :

Le {{chapo}} décrit l'objet du plugin, en terme de fonctionnalités ou services rendus à l'utilisateur.
-----------

{{{Installation}}}
dépendances, pré-requis

{{{Configuration}}}
spécifier s’il existe un bouton dédié..où ?

{{{Utilisations}}}
explications avec captures d’écran ou exemples de codes / boucles et  développements explicatifs (si besoin, découper en plusieurs sections..)

{{{Fonctionnement}}}
d'autres informations optionnelles, par exemple les indications de développement, bugs &toDo, modifications de la BdD à l'installation,  le cas de la desinstallation purgeant ou non la BdD....

{{{Références et liens}}}
site-exemple, sources de bibliothèques, autres guides,
    lien vers la page (de Carnet ?) doc developpeur et discussions d’extensions, trac..

{{{Explication de développement et todo}}}

Les réactions sous votre article lorsque vous l’aurez proposé à la publication ne devraient pas tarder (vous recevrez les notifications de son forum par mail) sinon après quelques jours, n’hésitez pas à relancer gentiment pour obtenir la publication.

Une des personnes qui administre le site vous créera alors une rubrique pour y accueillir votre article et vous en deviendrez administrateur restreint pour gérer les versions suivantes et les ajouts d’articles. Par la suite, pensez à intégrer vos nouveautés, les remarques et précisions à apporter au fil du temps.

2. Déclarez l’url de documentation dans votre plugin

L’URL de l’article de documentation que vous venez de rédiger est sous la forme http://contrib.spip.net/n°_id_article elle sera référencée automatiquement dans le site http://plugins.spip.net/ et s’affichera sur la page des plugins du site qui l’utilisera.

-  Vous êtes en SPIP2, dans plugin.xml utilisez la balise lien

<lien>https://contrib.spip.net/url_documentation</lien>


-  Vous êtes en SPIP3, dans paquet.xml
Pour rédiger proprement votre paquet.xml voir http://plugins.spip.net/redaction-d... ou pour vérifier la validité de votre paquet.xml http://plugins.spip.net/validation/

Les attributs « documentation », « demonstration », « developpement » sont les URL respectives de la documentation officielle du plugin, d’un site de démonstration et du lieu de développement du plugin

On mettra dans la balise <paquet>au minimum l’attribut documentation avec l’URL générée par contrib, ou seulement le numéro d’article (par exemple : http://contrib.spip.net/Depublie équivalent à https://contrib.spip.net/4484) :

<paquet
…
    documentation="http://contrib.spip.net/4484"
…
>

Voir l’exemple du plugin Dépublie
https://git.spip.net/spip-contrib-e...

3. Fabriquer et ajouter le Zip

L’ajout du zip à l’article est automatique à partir du moment où vous avez renseigné l’url dans son paquet.

Désormais sous GIT 1 tag = 1 zip
Les développements des contributions à SPIP sont effectués sous GIT
https://git.spip.net/spip-contrib-extensions/
Il suffit de créer un tag avec un numero de version (de la forme v1.2.3) et le zip est créé.

Si vous développez en dehors de git.spip.net
pour générer un zip en dehors de git.spip.net, ajoutez votre lien dans
https://git.spip.net/spip-contrib-outils/archivelists/src/branch/master/archivelist-externals.txt

4. Ajouter un logo à votre plugin

Créez un beau logo pour votre plugin, de format carré de préférence et ajoutez le en tant que logo de la rubrique, ainsi tous les articles enfants en hériteront.


Voyez aussi ce guide de rédaction pour les recommandations concernant l’esprit éditorial sur SPIP Contrib.

L’ajout des demandes de traduction se fait en ajoutant votre plugin sur https://git.spip.net/spip-contrib-outils/archivelists/src/branch/master/traductions.txt

Discussion

2 discussions

  • 1

    Bonjour,

    J’ai repéré 2 soucis de lien sur cette page :

    • Le lien vers la documentation « Voyez aussi ce guide de rédaction, qui présente l’esprit éditorial dans lequel les articles doivent être rédigés en général sur spip Contrib. » mène à une page 404.
      Peut-être à remplacer par cette page : https://contrib.spip.net/Tutoriaux-pour-Plugins ?
    • Le lien « réaliser un plugin pour SPIP2 allez plutôt ici http://www.spip.net/fr_article3448.html » mène à une page rédigée en catalan... Je n’ai pas trouvé d’équivalent en français. Dans ce cas, ça peut être intéressant de préciser la langue de la page de destination au niveau du lien.

    Bonne journée !

    • Bonjour Sandrine,
      j’ai réécrit l’article en lui apportant les modifications que tu as relevées.
      merci
      ++

    Répondre à ce message

  • A l’usage, d’autres préconisations :
    -  si l’explication du Fonctionnement interne n’est pas écrite, il peut néanmoins s’avérer utile de signaler explicitement le préfixe du plugin dans le paragraphe « Installation » ; éventuellement les tables et/ou champs optionnels dans la base...
    -  et prévoir un mot-clé précisant la compatibilité SQL étendue/préfixes des primitives utilisées..
    (ou avertissant dans le cas contraire !! )

    Répondre à ce message

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom