Documentation PHP automatique avec phpDocumentor sous Windows

Introduction

Laissons de côté un instant le Javascript et jQuery pour s’intéresser un peu au PHP. Ce qui suit est souvent un gros manque dans certains projets collaboratifs et conséquents en code : la documentation du code. Les développeurs les moins expérimentés sont très souvent réticents à l’idée de documenter leur travail, « on perd du temps », « j’ai pas besoin de doc, je sais me relire », et j’en passe.

La solution proposée dans cet article vous permettra de générer très proprement de la documentation de votre code PHP, à condition bien sûr que vous en fassiez un minimum.

phpDocumentor est un outil qui permet de générer une documentation automatique des codes sources PHP d’un projet. Il utilise une syntaxe particulière pour détecter votre documentation.

Vous pouvez voir une démo du rendu sur le site officiel.

Il faut savoir que phpDocumentor a besoin de PEAR pour fonctionner.

Installation de PEAR

Télécharger le fichier http://pear.php.net/go-pear.phar et le copier dans votre répertoire PHP, par exemple : C:\wamp\bin\php\php5.4.3

Se rendre ensuite avec l’invite de commandes dans ce répertoire : cd c:\wamp\bin\php\php5.4.3

Exécuter le fichier qui a été copié : php go-pear.phar

Quand il vous demande un choix, faire 11, ceci aura pour effet de renommer le fichier de configuration PEAR ; puis Entrer.

Taper ensuite $prefix\pear.ini

Quand il vous redemande un choix, faire Entrer.

Si il répond « Would you like to alter php.ini? », répondre Y.

Exécuter le fichier PEAR_ENV.reg afin d’intégrer les nouvelles variables d’environnement au système.

A ce propos, dans les variables d’environnement système (Windows + Pause), pour PATH, ajouter le chemin vers votre répertoire PHP : ;C:\wamp\bin\php\php5.4.3

Relancer l’invite de commandes car il recharge les variables d’environnement et mettre à jour PEAR avec : pear upgrade-all

On indique à PEAR le canal que l’on souhaite utiliser pour récupérer phpDocumentor : pear channel-discover pear.phpdoc.org

On installe phpDocumentor : pear install phpdoc/phpDocumentor-alpha

Configuration de PHP

Dans le fichier C:\wamp\bin\php\php5.4.3\php.ini

Retirer le ; devant les lignes suivantes :

  • php_fileinfo
  • php_xsl

Passer le paramètre memory_limit à 512M au lieu de 128M.

Ajout des graphiques pour phpDocumentor

Télécharger le package Windows : Graphviz.

Relancer l’invite de commandes et vérifier que la commande dot est reconnue par le système.

Générer la documentation

Aller dans le répertoire de votre site : cd c:\wamp\www\monsite

La commande phpdoc -d . -t docs génère à partir de l’endroit où vous êtes, la documentation vers le répertoire docs.

Tous les fichiers .php situés à la racine du chemin où vous vous trouvez et dans ses sous-dossiers seront parsés afin de détecter la présence de DocBlocks. Toutes les infos trouvées se trouvent dans le fichier docs/structure.xml.

Vous pouvez ensuite vous rendre sur localhost/monsite/docs et voir le résultat.

Syntaxe à utiliser dans les codes sources

Pour que phpdoc détecte la documentation intégrée dans les fichiers, il faut utiliser des DocBlocks.

<?php
/**
* This is the short description for a DocBlock.
*
* This is the long description for a DocBlock. This text may contain
* multiple lines and even some _markdown_.
*
* * Markdown style lists function too
* * Just try this out once
*
* The section after the long description contains the tags; which provide
* structured meta-data concerning the given element.
*
* @author  Syl <contact@chez-syl.fr>
*
* @since 1.0
*
* @param int    $example  This is an example function/method parameter description.
* @param string $example2 This is a second example.
*/
?>

Se reporter à cette page pour plus d’informations sur la syntaxe.

Installation de template

Pour installer ou changer un template, aller dans le répertoire du site : cd c:\wamp\www\monsite

Lancer phpdoc -d . -t src/docs --template old-oceanold-ocean est le nom du template. Liste des templates officiels

Conclusion

Il ne vous reste plus qu’à documenter vos fichiers PHP avec la bonne syntaxe. Pour ensuite voir les changements dans votre interface phpdoc, il faut relancer le parsing avec la commande ci-dessus. ;)

Vous aimerez aussi...