Ce chapitre décrit précisément comment écrire une documentation en utilisant un des formats supportés. Ce chapitre est aussi bien destiné aux développeurs PEAR qui travaillent sur un package PEAR existant qu'à ceux qui prévoient d'en créer un nouveau.
Docbook est un dialecte XML utilisé par un grand nombre de projets pour maintenir leur documentation. Par exemple, Docbook est utilisé pour les documentations des projets OpenSource KDE et PHP. PEAR a opté pour l'usage de DocBook, parce que nous croyons qu'il fournit une base solide pour la documentation technique des packages de PEAR.
Le désavantage de DocBook est qu'il est relativement difficile d'utilisation. Les essais sur la documentation exige qu'un certain nombre d'outils soient installés et on doit apprendre un dialecte (pas très compliqué) de XML. Une fois qu'on est familier avec la façon dont DocBook fonctionne, l'écriture de la documentation devient appréciable.
Le livre [DocBook: The Definitive Guide], écrit par Norman Walsh et Leonard Muellner et publié par O'Reilly & Associates, Inc., est disponible en ligne. Il est aussi disponible en français Il propose une ressource importante pour les personnes déésireuses d'apprendre DocBook.
Lisez plus particulièrement la section << DocBook Element Reference >> de ce livre. Cette section fournit des informations détaillées sur chaque élément, y compris quels éléments peuvent (et doivent) être utilisés en tant que parent et enfant.
Même si du XML Docbook peut (comme n'importe quel fichier XML) être écrit avec un simple éditeur de texte, il vous faudra installer des logiciels sur votre ordinateur afin de vérifier la validité de votre documentation. Une liste des logiciels nécessaires et les instructions d'installation correspondantes peuvent être trouvées dans la Documentation HOWTO de PHP. En plus de fournir des informations sur les logiciels, ce HOWTO fournit une multitude d'informations utiles non décrites dans ce chapitre. Nous vous encourageons à le lire complétement (Le chapitre II peut être sauté, il ne contient que des informations spécifiques à PHP)
Malheureusement, l'installation de ces logiciels peut être difficile dans certaines circonstances. Si vous n'êtes pas capable de les faire fonctionner, n'utilisez pas celà comme excuse pour ne pas écrire de documentation. Il y a deux serveurs de test qui, toutes les deux heures, téléchargent automatiquement la documenation PEAR depuis CVS et construit le manuel. Chaque erreur de parsage que vous modifiez sera monté dans les logs de la prochaine construction :
| http://www.appelsiini.net/~tuupola/php/peardoc2/peardoc.txt (time zone: EET = UTC+2, EEST = UTC+3) |
| http://pear.php-tools.net/peardoc.log (time zone: CET = UTC+1, CEST = UTC+2) |
| http://pear.php-tools.net/peardoc-error.log |
| http://www.appelsiini.net/~tuupola/doc/peardoc/ |
| http://pear.php-tools.net/peardoc/ |
| Avertissement |
Le manuel de PEAR sur le site web est regénéré seulement une fois par semaine. Toutes les erreurs de validation XML causent un echec de génération. Si la regénération échoue, l'ancienne version est réutilisée mais cela veut dire que le manuel est dépassé. Et donc, toujours vérifier les logs des génération test pour vous assurer que vos changement sont valides. Plus important encore, n'éffectuez aucun commit ou updates juste avant la regénération principale qui se produit le dimanche vers midi UTC. |
Une fois les logiciels installés, il vous faut récupérer les dernières versions disponibles des sources XML via le dépôt CVS de PEAR :
$ cvs -d :pserver:<user>@cvs.php.net:/repository login
[password]
$ cvs co peardoc
|
Si vous n'avez pas de compte pour cvs.php.net, utilisez cvsread comme nom pour le login. Et quand le mot de passe vous est demandé, utilisez phpfi.
Après cette commande, votre répertoire local ./peardoc contiendra une copie locale des dernières sources. Si vous n'êtes pas familier avec CVS, alors l'ouvrage en ligne << Open Source Development with CVS >> peut vous fournir toute l'information nécéssaire.
Ce chapitre va préciser les détails sur la structure des dossiers. Le chemin peardoc/fr/package/ est l'endroit où créer votre documentation. Si vous avez des questions sur la structure de la documentation, contactez la liste de diffusion de la documentation de PEAR.
Au lieu d'une longue et ennuyeuse description de l'utilisation de DocBook pour la écrire la documentation, nous voudrions vous diriger à un groupe de << documents de référence >>, avec lequels vous devriez apprendre rapidement :
L'arbre CVS est un ensemble complet de template DocBook XML. Ces fichiers fournissent une norme de l'apparence que doit avoir la documentation de PEAR.
La manière la plus simple de les utiliser est de les copier dans votre dossier de travail, de les renommer en conséquence, éditer le contenu pour qu'il corresponde à votre programme et puis pour les uploader dans le repository CVS de votre package.
La documentation pour HTTP_Request, qui est un package relativement petit, se compose seulement d'un groupe de documentation pour utilisateur final, qui décrit tous les dispositifs de base du package. Chaque description de fonctionnalité inclut au moins un exemple. Pour les petits packages avec seulement une poignée de méthodes, ce type de documentation est absolument suffisant.
XML_Beautifier est un package qui est également relativement compact, mais qui permet différentes options de configuration. Ces options sont décrites dans la documentation. En plus, la documentation donne des exemples d'utilisation et (à la différence de HTTP_Request) inclut également la documentation de l'API pour ses méthodes.
DB est un gros package de PEAR et dispose d'une excellente documentation, y compris des exemples d'utilisation. La documentation de DB adhère soigneusement au formatage indiqué dans peardoc/authoring. Le lien précédent pointe vers le code source DocBook dans le CVS. Cela peut être très utile de regarder le HTML généré depuis ces sources.
En plus des exemples ci-dessus, vous trouverez beaucoup plus d'exemples de documentation en passant en revue le repository de peardoc, qui contient votre version locale de l'arbre de CVS. Le dossier peardoc/en/packages/ devrait particulièrement vous intèresser. Vous pouvez également passer en revue le module CVS en utilisant l'interface web, incluant l'XML brut pour le fichier que vous être en train de lire.
La traduction de la documentation est une autre tâche importante. Il n'y pas que traduire les nouvelles documentations dans les langues existantes, les nouvelles langues sont les bienvenues. Aussi, les traductions existantes doivent être maintenue à jour en fonction des changements de la version anglaise de référence. Une aide sur la façon d'effectuer une traduction est fournie dans la section de suivi de version du manuel.
Nous sommes bien conscient de ne pas couvir toutes les questions à propos de l'écriture de la documentation en docBook dans ce chapitre. Si vous avez d'autres questions ou que vous rencontrez le moindre problème, n'hésitez pas à contacter l'équipe de documentation via pear-doc@lists.php.net. Pour rejoindre la liste pear-doc, envoyez un email à pear-doc-subscribe@lists.php.net.
| Précédent | Sommaire | Suivant |
| Représentation des couleurs dans les package PEAR | Niveau supérieur | Conseils pour une bonne documentation |