Tutorial d'installation et d'utilisation (et de configuration d'un fichier .ini) pour phpdocumentor
Tutorial d'installation et d'utilisation (et de configuration d'un fichier .ini) pour phpdocumentor
Introduction
Bonjour @ tous,
Bienvenue dans mon tout premier tutoriel :-> J'espère qu'il vous sera utile !
Je vais vous expliquer comment installer phpDocumentor correctement et à l'utiliser rapidement (donc, à générer une documentation).
J'ai vu sur le net que beaucoup - pour ne pas dire énormément - de gens ont des erreurs avec phpDocumentor, et n'arrivent pas à l'utiliser. C'est pour tout ceci que je me suis décidé à faire ce tuto.
A oui, par contre, ce tuto n'explique pas comment documenter votre code, désolé. Reportez vous à la doc de phpDocumentor, elle est faite pour ça !
INSTALLATION
/!\ AVERTISSEMENT /!\
CETTE EXPLICATION D'INSTALLATION EST UNIQUEMENT VALABLE POUR L'UTILISATION DE phpDocumentor AVEC docBuilder, SON INTERFACE WEB.
Tout d'abord, téléchargez la dernière version stable de phpDocumentor, ICI. .
Lorsque vous l'avez téléchargé, "dézippez" le contenu du fichier PhpDocumentor-1.3.x.zip dans la racine de votre serveur web (ou de votre hébergeur).
ATTENTION : Laissez l'architecture des dossiers du fichier ZIP telle-quelle. Ne touchez à rien.
Admettons que vous possédez un serveur d'évaluation (comme moi), et que la racine de votre serveur local est C:\web\www, vous installerez donc phpDocumentor dans ce chemin. Normalement, après le dézippage, un dossier nommé exactement PhpDocumentor devra être dans ce répertoire (ce qui donnera donc C:\web\www\PhpDocumentor).
En admettant toujours que vous possédez un serveur d'évaluation dont la racine est C:\web\www, pointez votre navigateur vers cette URL : http://localhost/PhpDocumentor/docbuilder/. Une page nommée docBuilder - phpDocumentor web interface devra s'afficher.
Si vous avez tout réussi jusqu'ici, c'est totalement bon. On passe à l'utilisation rapide.
UTILISATION RAPIDE
/!\ ATTENTION /!\
AVANT TOUTE CHOSE, VOUS DEVEZ CONFIGURER LE PARAMÈTRE 'max_execution_time' DE VOTRE FICHIER php.ini SUR AU MOINS 300 (secondes).
SI VOUS NE POUVEZ PAS, FAITES UN ini_set() SUR CE PARAMÈTRE.
Personnellement, je l'ai mit sur 0 ainsi que 'max_input_time', comme ça je suis tranquille.
Dans la barre de menu, cliquez - si vous voulez - sur Config. Nous ne nous préoccuperons pas de cette section, sauf si vous voulez utiliser un fichier de configuration .ini. Si vous voulez en utiliser un (ce qui est très pratique), allez au III.) CONFIGURATION D'UN FICHIER DE CONFIGURATION.INI plus bas.
Cliquez donc sur Files. Quatres textarea doivent apparaître :
- Files to parse : une liste de fichiers PHP séparés par des virgules que phpDocumentor doit analyser (pour l'instant, on ne s'en préoccupe pas).
- Directory to parse : une liste de répertoires séparés par des virgules que phpDocumentor doit analyser. Par exemple, vous avez installé PhpMyadmin dans C:\web\www\phpmyadmin et vous aimeriez une doc de celui-ci. Vous entrerez donc dans le champ Directory to parse ceci : C:\web\www\phpmyadmin
- Files to ignore : Une liste de fichiers ou de répertoires séparés par des virgules dont phpDocumentor ne doit pas s'en soucier. Très utile. Par exemple, vous interdisez à phpDocumentor d'analyser les fichier images. Vous mettrez donc dans ce textarea ceci : *.jpg, *.jpeg, *.gif, *.png
- Packages to parse : Euh, je pourrait pas vous expliquer ceci... voyez la doc de phpDocumentor. Moi je ne programme pas en POO.
- Working Directory : </gras>je ne sait pas trop à quoi ça sert, ça...
Ok. Quand on a fait tout ceci correctement, on clique sur Output. Ah, c'est très important le Output ! Dans Output, on a deux champs de texte (enfin non, un champs de texte et un textarea) :
- Target : C'est en fait la cible où les fichiers générés par phpDocumentor seront créés (exemple : C:\web\www\doc)
- Output Format : Le format de sortie. Vous avez le choix entre une doc :
- avec des frames (avec plusieurs templates !)
- format Smarty (encore plusieurs templates)
- format PDF
- format XML:DocBook/peardoc2.
Vous pouvez choisir plusieurs formats de sorties en même temps, mais je ne le conseille pas.
Exemple : vous choisissez le format de sortie HTML:frames:phpedit uniquement. Lorsque vous l'aurez sélectionné dans le menu déroulant Output type:Converter name:template name, cliquez sur Add the converter in the help box. Normalement, si vous n'avez pas touché à la textarea Output Format depuis le début, il devrait y avoir, dans cette textarea, ceci : HTML:Smarty:default, HTML:frames:phpedit
Si vous ne voulez que faire une génération de documentation qu'avec HTML:frames:phpedit, virez le HTML:Smarty:default avec la virgule.
Bon, quand tout est fait, on peut cliquer éventuellement sur Options. Dans Options on a :
- Generated Documentation Title : le titre de la documentation générée
- Default Package Name : le nom par défaut du package
Le reste ne nous intéresse pas, vu que c'est un tuto pour une utilisation rapide ! Voyez la doc de phpDocumentor pour savoir ce que veux dire tout le reste...
ET ENFIN, il ne nous reste plus qu'à cliquer sur le bouton create, vers le bas à droite !
Lorsque vous aurez cliqué dessus, des choses vont s'écrire dans la frame d'en dessous, du genre :
Parsing Files ...
PHP Version 5.2.0RC2-dev
phpDocumentor version 1.3.1
Parsing configuration file phpDocumentor.ini...
done
using tokenizer Parser
Grabbing README/INSTALL/CHANGELOG
done
Tutorial/Extended Documentation Parsing Stage
done
General Parsing Stage Reading file C:/web/www/PhpDocumentor/docbuilder/actions.php -- Parsing file
WARNING in actions.php on line 35: Page-level DocBlock precedes "include_once actions.php", use another DocBlock to document the source element
Reading file C:/web/www/PhpDocumentor/docbuilder/blank.html -- File not parsed, not a php file
Reading file C:/web/www/PhpDocumentor/docbuilder/builder.php -- Parsing file
.....
et, tout à la fin de l'analyse et de la génération des fichiers, il y aura écrit ceci :
Operation Completed!!
Si vous voyez ce texte affiché, cela veux dire que vous avez compris ce tuto ! Vous pourrez donc voir le chef d'oeuvre créé par phpDocumentor dans le répertoire cible !
CONFIGURATION D'UN FICHIER .INI
Un fichier .ini de phpDocumentor contient toutes les informations pour la génération d'une doc. Vous n'aurez donc pas besoin de remplir à chaque fois les champs de texte. Tous les fichier .ini sont situés dans [racine]/PhpDocumentor/user. Suivez ce qui suit pour en configurer un.
Tout d'abord, copiez le fichier makedocs.ini (le plus simple), puis renommez le comme vous voulez. Ouvrez le avec Notepad (ou autre). Voici les différentes valeurs de configuration :
- title : C'est le nom général de votre documentation.
- hidden : Normalement, elle est sur false, laissez comme ça.
parseprivate : analyse aussi les éléments marqués d'un @access private. off par défaut.
- javadocdesc : ??
- customtags : vos tags personnalisés séparés par des virgules. Si vous ne voulez pas rajouter de tags perso, passez au suivant.
- defaultpackagename : le nom du package par défaut (si phpDocumentor ne trouve pas de @package dans un fichier)
- quiet : ??
- target : C'est en fait la cible où les fichiers générés par phpDocumentor seront créés (exemple : C:\web\www\doc)
- packageoutput : ??
- filename : ??
- directory : une liste de répertoires séparés par des virgules que phpDocumentor doit analyser. Par exemple, vous avez installé PhpMyadmin dans C:\web\www\phpmyadmin et vous aimeriez une doc de celui-ci. Vous entrerez donc dans le champ Directory to parse ceci : C:\web\www\phpmyadmin
- ignore : Une liste de fichiers ou de répertoires séparés par des virgules dont phpDocumentor ne doit pas s'occuper. Très utile. Par exemple, vous interdisez à phpDocumentor d'analyser les fichier images. Vous mettrez donc dans ce textarea ceci : *.jpg, *.jpeg, *.gif, *.png
- output : Le format de sortie. Vous avez le choix entre une doc :
- avec des frames (avec plusieurs templates !)
- format Smarty (encore plusieurs templates)
- format PDF
- format CHM
- format XML:DocBook/peardoc2.
ATTENTION : le formatage de cette valeur de configuration doit être de la forme Output type:Converter name:template name (ex : HTML:frames:DOM/earthli
Voilà, vous avez configuré un fichier .ini pour phpDocumentor ! Pour l'utilisez, pointez votre navigateur sur http://localhost/PhpDocumentor/docbuilder/ (si vous possédez un serveur d'évaluation dont la racine est C:\web\www). Cliquez sur Config dans la barre de menu. Dans le menu déroulant Choose a config, sélectionnez un fichier de configuration (en l'occurrence, celui que vous avez créé juste avant), puis cliquez sur Go.
Voilà c'est la fin de ce tuto ! Je voulais juste dire : moi aussi au début, j'arrivait pas du tout à faire fonctionner et à utiliser phpDocumentor mais un jour (le 28/10/06 pour être plus précis) j'ai réussi par le plus grand des hasard et en fait ce tuto c'est exactement ce que j'ai fait ce jour là pour le faire fonctionner.
Par la suite, je ferait - peut-être - des autres tutos sur phpDocumentor.
Aller, @+++ !
- Phpdocumentor tutorial
- Phpdocumentor ✓ - Forum PHP