Voilà, voilà... Fin de l'aventure...

 

Fermeture de kolossaldrupal.org dans...


Bonjour tout le monde,

Drupal évolue, les versions changent et Kolossaldrupal.org était essentiellement consacré à la version 6 de Drupal.

Autant dire que les infos présentées ici commencent à dater...

Faute de temps, je ne peux plus garder le site Kolossaldrupal à jour...

Je vous aurais bien proposé de reprendre le flambeau mais... c'est tellement simple de nos jours de se faire son propre site à soi...Pourquoi s'embêter alors ? :-)

Ce site restera donc en l'état, tel qu'il était en 2011...

Ah la la ! Cela ne nous rajeunit pas !

Manuel Vila - Avril 2016

Règles de documentation des modules

Référence sur drupal.org : 8 Mars 2009 – 03h59 - http://drupal.org/node/161085


Lorsque vous soumettez (ou maintenez) des modules, l’existence d’une bonne documentation est vitale pour ceux qui viennent après vous. De nombreux ouvrages en parlent, et tout développeur digne de ce nom a son idée sur ce qui constitue une bonne documentation. Il y a toujours une ligne de démarcation entre trop de documentation et pas assez.

Les indications qui suivent doivent être utilisées pour les modules qui feront partie des modules contributifs de Drupal.

Obligations de base

Ayez un README utile

Tous les modules, sauf les plus simples, doivent être accompagnés d’un README.txt. Ce fichier doit contenir un aperçu de ce que fait le module et de comment l’utiliser. Ce peut être une copie du résumé figurant sur la page du projet. Il est également conseillé de faire un lien direct vers le README.txt depuis la page du projet :

http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/modulename/...

Ce fichier doit donner suffisamment d’informations à l’utilisateur pour qu’il puisse évaluer si le module correspond à ses besoins avant qu’il ne le télécharge et ne l’installe.

Utiliser hook-help

Tous les modules, sauf les plus simples, doivent, dans une certaine mesure, implémenter hook_help(). Reportez-vous à Embedded documentation style guide pour voir comment structurer votre documentation. Sinon, vous pouvez simplement inclure le README avec une fonction comme :

<?php
/**
* Implementation of hook_help().
*/
function mymodule_help($section) {
  switch (
$section) {
    case 
'admin/help#mymodule':
      
// Return a line-break version of the module README
      
return filter_filter('process'2NULLfile_get_contentsdirname(__FILE__)."/README.txt") );
  }
}
?>

Les pages d’aide Drupal sont évidemment l’endroit pour accéder aux informations sur votre module, à un niveau utilisateur ou développeur.

Dites aux utilisateurs ce que fait le module

Le README et l’aide doivent décrire comment accéder aux fonctionnalités du module.

Si le module fournit quelques éléments de menus, indiquez les chemins pour que l’utilisateur n’ait pas à les chercher dans l’interface d’administration.

S’il modifie des Interface Utilisateur de formulaires avec l’API Forms, dites à l’utilisateur ce qu’il doit chercher pour être sûr que ça marche.

Si le module a besoin d’un paramétrage, fournissez le lien vers la page d’administration et écrivez éventuellement un petit guide de démarrage.

Réfléchissez au nom du « package »

Vous pouvez définir un groupe dans le fichier module.info. Beaucoup de modules n’utilisent pas du tout de « package » groupe. Citation de la page « Comment écrire les fichiers .info » : « En règle générale, ce champ ne devrait être utilisé que par les grands  modules multi-package, ou par les modules qui étendent ces packages, comme CCK, Views, E-Commerce, Organic Groups et assimilés ». Si vous avez une utilisation valable du package name, utilisez la liste existante des groupes de projets pour intituler votre module, veillez au respect des majuscules/minuscules.

Documentez toutes les fonctions correctement

Dans vos modules, vous êtes invité à utiliser des commentaires formatés Doxygen . Bien que cela ressemble parois à une tarte à la crème, apprenez à les apprécier, puisque ce sont ces commentaires qui alimentent l’intégralité du site api.drupal.org et peuvent faire la même chose pour vous en utilisant le module API. Votre code peut être auto-documenté... gratuitement !

De plus, beaucoup d’IDE sont à même de détecter automatiquement les blocs de documentation Doxygen, et de fournir une aide contextuelle. Sans compter les avantages évidents pour les personnes qui lisent votre code.

Lisez les règles d’écriture de commentaires et notamment m’utilisation de la directive @ingroup.

Pratiques recommandées

Les suggestions qui suivent ne sont pas sacro-saintes mais peuvent aider à rendre votre module plus developpeur-friendly.

  • Même si votre module n’a pas besoin d’une fonction hook_install, il est sympa d’afficher un mot confirmant qu’il a été installé et prêt à l’emploi. La fonction hook_install se trouve dans le fichier module.install :
    <?php
    /**
    * Implementation of hook_install().
    */
    function mymodule_install() {
      
    drupal_set_message(st("YourModule settings are available under !link",
        array( 
    '!link' => l('Administer > Site configuration > Your Module ',  'admin/settings/yourmodule/settings' ) )
      ));
    }
    ?>

    Notez que dans les fichiers .install, vous devez utilise st() plutôt que t().
  • Créez des liens renvoyant aux pages d’utilisation et de paramétrage du module (ainsi qu’à sa page d’aide). Ces pages se trouvent souvent à plusieurs clics de souris les unes des autres ! Utiliser la méthode hook_help pour ajouter un paragraphe en haut des pages concernées peut aider. Des liens de ce type sont probablement plus utiles que toutes sortes de chapitres d’explications dans un document annexe.
  • Quand vous créez votre page de projet, activez le lien vers « Browse CVS Repository ».
  • Si cela est utile, n’hésitez pas à ajouter de la documentation supplémentaire comme partie intégrante du projet, dans un sous-dossier appelé docs/.
  • Les copies d’écrans de l’Interface Utilisateur ou des schémas des processus sont très utiles. Même si vous ne pouvez pas inclure des images dans la page de votre projet, vous pouvez créer des liens directs vers une documentation supplémentaire dans le CVS aux fins d’illustration.
  • Essayez d’installer et d’exécuter votre code via le module API. Ce n’est pas la panacée mais cela indiquera le niveau de votre documentation et ce qu’elle pourrait être si vous en modifiez un peu le formatage.
  • Si vous hébergez votre développement ou votre site Drupal de démo quelque part, pensez à rendre disponible votre documentation du code  et à créer des liens vers elle depuis votre page du projet.
  • Installez et exécutez le module Coder. Il est franchement tatillon mais il rendra votre code plus facile à maintenir pour les utilisateurs.
  • Utilisez des comentaires sur une ligne
    // Sur leur propre ligne, avant leur sujet, en utilisant correctement majusculeset ponctuation.

    pour expliquer les points les plus délicats de votre code. La documentation palcée ici l’est pour les mainteneurs et les développeurs qui liront ’on l’espère) le code-source aussi facilement que la prose qui l’entoure. Les commentaires d’éclaircissements, les TODO, les restrictions connues, les aides-mémoire, les excuses pour le code légèrement surabondant et autres avertissements se mettent ici.
  • Utilisez sans compter les références Doxygen @see pour lier les fonctions connexes.
  • En ayant des fonctions courtes (moins de 1 page) vous n’aurez pas rédiger beaucoup de détails d’implémentation.
  • Encouragez les contributeurs à améliorer la documentation. Un utilisateur peut parfaitement contribuer pour rien de plus que clarifier des commentaires et cette participation a sa place dans le CVS. Souvent, un regard extérieur verra les choses qui demandent un peu plus d’explications alors qu’elles vous sont familières.
  • Écrire un aperçu des buts du code et de sa méthodologie globale dans la section @file est souvent une idée très utile. Cela peut même aider à la conception du code durant la phase de planification.