Bonjour @ tous, bienvenue dans mon tout premier tutorial :-> 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 !

Pour toute question, n'importe laquelle, contactez moi ici : epoc@hotmail.fr

I.) 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éussit jusqu'ici, c'est totalement bon. On passe à l'utilisation rapide.

II.) UTILISATION RAPIDE :

/!\ ATTENTION /!\
AVANT TOUT CHOSE, VOUS DEVEZ CONFIGURER LE PARAMETRE 'max_execution_time' DE VOTRE FICHIER php.ini SUR AU MOINS 300 (secondes).
SI VOUS NE POUVEZ PAS, FAITES UN ini_set() SUR CE PARAMETRE.
Personnellement, je l'ai mit sur 0 ainsi que 'max_input_time', comme ça je suis tranquile.

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 dont phpDocumentor doit analyser (pour l'instant, on s'en fou).
• Directory to parse : une liste de répertoires séparés par des virgules dont phpDocumentor doit analyser. Par exemple, vous avez installé PhpMyadmin dans C:\web\www\phpmyadmin et vous aimerez 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 doit s'en foutre. 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 expliquez ceci... voyez la doc de phpDocumentor. Moi je programme pas en POO.
• Working Directory : 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 CHM
  • 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 comprit ce tuto ! Vous pourrez donc voir le chef d'oeuvre créé par phpDocumentor dans le répertoire cible !

III.) 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 :

1. title : C'est le nom général de votre documentation.
2. hidden : Normalement, elle est sur false, laissez comme c'est.
3. parseprivate : analyse aussi les éléments marqués d'un @access private. off par défaut.
4. javadocdesc : ??
5. customtags : vos tags personalisés séparés par des virgules. Si vous ne voulez pas rajouter de tags perso, passez au suivant.
6. defaultpackagename : le nom du package par défaut (si phpDocumentor ne trouve pas de @package dans un fichier)
7. quiet : ??
8. target : C'est en fait la cible où les fichiers générés par phpDocumentor seront créés (exemple : C:\web\www\doc)
9. packageoutput : ??
10. filename : ??
11. directory : une liste de répertoires séparés par des virgules dont phpDocumentor doit analyser. Par exemple, vous avez installé PhpMyadmin dans C:\web\www\phpmyadmin et vous aimerez une doc de celui-ci,, vous entrerez donc dans le champ Directory to parse ceci : C:\web\www\phpmyadmin
12. ignore : Une liste de fichiers ou de répertoires séparés par des virgules dont phpDocumentor doit s'en foutre. Très utile. Par exemple, vous interdisez à phpDocumentor d'analyser les fichier images. Vous mettrez donc dans ce textarea ceci : *.jpg, *.jpeg, *.gif, *.png
13. 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'occurence, 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, @+++ !

Pour toute question, n'importe laquelle, contactez moi ici : epoc@hotmail.fr