É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 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.

updated on 7 March 2021

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
      ++

    Reply to this 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 !! )

    Reply to this message

Ajouter un commentaire

Who are you?
[Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom