SPIP-Contrib

SPIP-Contrib

عربي | Deutsch | English | Español | français | italiano | Nederlands

289 Plugins, 197 contribs sur SPIP-Zone, 88 visiteurs en ce moment

Accueil > Vie de SPIP et autour de SPIP > Charte et vie SPIP-Contrib > Écrire la documentation d’un plugin SPIP

Écrire la documentation d’un plugin SPIP

25 février 2014 – par touti – commentaires

5 votes

Cet article explique en 4 étapes comment créer les liens de 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, suivez l’excellent tutorial de marcimat http://marcimat.magraine.net/Chats-... ou bien utilisez la fabrique qui permet d’automatiser la création de plugins La Fabrique

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.

1. Rédigez l’article de documentation

Si vous n’êtes pas encore auteur·e, inscrivez-vous puis allez dans l’espace de rédaction de SPIP-Contrib https://contrib.spip.net/ecrire pour y rédiger votre article. Pensez à ajouter un logo, des mots-clefs, puis demandez la publication.

On peut proposer une structure-type à cet article, une trame générale, dont le respect facilitera l’utilisation ultérieure de ces articles comme documentation :

Un chapo décrit l’objet du plugin, en terme de fonctionnalités ou services rendus à l’utilisateur.

Les sections les plus fréquentes listées ci-dessous donnent un ordre de lecture et de compréhension logique :
-  installation : et dépendances, pré-requis
-  configuration (si elle existe) - 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..

Un exemple de code à reprendre dans votre texte

{{{installation}}}

{{{configuration}}}

{{{utilisations}}}

{{{fonctionnement}}}

{{{références et liens}}}

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

Pensez à faciliter le travail des administrateur de Contrib : rajouter les mots-clés à utiliser pour :

  • le flux des plugins ; la/les versions de SPIP
  • le type de contribution = plugins[112] ou documentation code[222] ..merci.

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

Un administrateur du site vous créera une rubrique pour y accueillir votre article et vous en deviendrez administrateur restreint pour gérer les versions suivantes et les ajouts d’articles. Il serait d’ailleurs de bonne pratique que vous intégriez ultérieurement vos nouveautés, ou les remarques et précisions apportées au fil de messages du forum, au sein de l’article principal..

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

Cette URL [1] sera affichée sur la page des plugins du site qui l’utilisera
et sera également référencée automatiquement dans le site http://plugins.spip.net/ si vous disposez d’un zip.
-  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
-  L’écriture d’un plugin pour SPIP2 nécessite un plugin.xml

En tant qu’auteur de cet article, vous serez joignable par les utilisateurs qui publieront sur son forum.

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 est équivalent à https://contrib.spip.net/4484) :

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

Voir l’exemple du plugin Dépublie
http://zone.spip.org/trac/spip-zone...

3. Fabriquez et ajoutez le Zip

voir https://plugins.spip.net/distribuer-une-contribution.html

-  Vous avez commité (voir SVN Publier son projet via SVN) votre plugin sur la Zone SPIP http://zone.spip.org/trac/spip-zone/. Pour fabriquer automatiquement un fichier facilement installable grâce au format compressé .zip vous devez déclarer votre plugin dans archivelist.txt
svn://zone.spip.org/spip-zone/archivelist.txt Publier archivelist.txt via svn/terminal
Voici la procédure à lancer sur votre terminal pour récupérer uniquement le archivelist.txt de spip-zone :

   
   mkdir spip-zone
   cd spip-zone
   svn co svn://zone.spip.org/spip-zone/ . --depth empty
   svn up archivelist.txt


-  Ou bien vous avez développé votre plugin SPIP de votre côté, que vous avez déjà zippé et vous souhaitez le partager sur SPIP-Contrib

Ajoutez le Zip en tant que document distant
Lorsque le zip est généré depuis archivelist.txt (donc la Zone SPIP) vous le retrouvez dans la page des plugins générés automatiquement http://files.spip.org/spip-zone/, copiez son URL.

Dans l’article, ajoutez le document distant en collant son URL.

4. Ajoutez le flux RSS des modifications SVN

Réservé aux administrateurs à partir du moment où la rubrique existe. Il est conseillé d’effectuer cet ajout après publication de l’article.

Sur la page track de votre plugin, par exemple http://zone.spip.org/trac/spip-zone/browser/_plugins_/agenda/trunk cliquez à droite sur Revision Log puis sur le flux RSS qui se trouve en bas de la page http://zone.spip.org/trac/spip-zone....
Créez un nouveau site dans la rubrique de votre article et copiez l’URL dans le flux de syndication.

Petits plus

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

Notes

[1Normalement celle de l’article de documentation que vous venez de rédiger, sous la forme http://contrib.spip.net/{n°_id_article}..

Dernière modification de cette page le 28 juin 2017

Retour en haut de la page

Vos commentaires

  • Le 26 juin 2017 à 14:30, par Sandrine En réponse à : Écrire la documentation d’un plugin SPIP

    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 !

    Répondre à ce message

  • Le 12 novembre 2014 à 12:56, par YannX En réponse à : Écrire la documentation d’un plugin SPIP

    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

Répondre à cet article

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 Les choses à faire avant de poser une question (Prolégomènes aux rapports de bugs. )
Ajouter un document

Retour en haut de la page

Ça discute par ici

  • Visualiser un PDF dans un article

    13 juin – commentaires

    SoyezCréateurs utilise un modèle pour afficher un PDF dans e corps d’un article Un peu d’histoire Avant, les navigateurs n’incluaient pas de lecteur PDF nativement ce qui avait conduit à la création du plugin Lecteur pdf javascript pdf.js. Mais, (...)

  • Intégrer un calcul d’itinéraire dans une page

    9 mai – commentaires

    Ce modèle SPIP permet d’intégrer un calcul d’itinéraire dans vos articles. Attention, cet outil nécessite une clef d’API Google Maps ! Clef d’API Google Maps Muni de votre compte gmail, rendez-vous sur Obtenir une clé/authentification. Vous (...)

  • odt2spip v3+ : création d’articles à partir de fichiers textes

    11 octobre 2017 – commentaires

    Ce plugin permet de générer des articles SPIP à partir du téléversement de fichiers au format .ODT (OpenOffice ou LibreOffice Writer). Il gère la majorité des raccourcis typographiques, détecte les différents niveaux de titre et fait l’intégration des (...)

  • Personnalisation graphique du squelette SoyezCréateurs

    19 août 2009 – 109 commentaires

    Il est possible de personnaliser l’affichage du squelette SoyezCréateurs de manière plus ou moins profonde. Changement dans les couleurs via CFG La page de CFG des couleurs de SoyezCreateurs : ecrire/ ?exec=cfg&cfg=soyezcreateurs_couleurs (...)

  • ORR v2

    21 mai 2013 – 102 commentaires

    ORR, le plugin d’Organisation des Réservations et des Ressources passe en version 2, avec quelques nouveautés attendues. Je ne reprendrai pas les explications données dans la version 1. Les nouveautés : 1. Gestion des autorisations Le principe (...)