Construire la documentation d’une application PHP

© Christian PAULUS. Document créé le 17 avril 2011 , mis à jour le 17 avril 2011.

Savoir où l'on veut aller, c'est très bien. Mais il faut encore montrer qu'on y va. Emile Zola

Accueil du site > Astuces > PHP > Construire la documentation d’une application PHP

PhpDocumentor 1.4.3 / MacOsX 10.6 (Snow Leopard)

Mots-clés

Même rubrique

Construire la documentation d’une application PHP automatiquement est à la portée de quelques clics, à condition bien sûr que ledit code PHP soit proprement commenté.

Un commentaire reconnu par PhpDocumentor est du style commentaire pour le langage C. Le tag d’ouverture doit contenir 2 astérisques :

<?php/**
 * Ce commentaire concerne le fichier PHP
 * car il est le premier commentaire.
 * Il sera affiché dans la documentation
 */
/**
 * Ce commentaire concerne la fonction foo()
 * Il sera affiché dans la documentation concernant cette fonction.
 * Il précisera le type de résultat retourné. 
 * @return int|string un entier ou une chaîne
 */
function foo ($mixed) {
 return ($mixed);
}
?>

Ce qui donnera en version web au format HTML:Smarty:HandS :

PNG - 53.6 ko

On parle là de PHPDoc ou DocBlock.

Il est possible de décrire un fichier, une fonction, une globale, une classe, etc. Si besoin, consulter le manuel PhpDoc phpDocumentor Guide to Creating Fantastic Documentation.

PhpDocumentor propose même plusieurs formats de documentation : site HTML du style de la documentation en ligne de php.net ; un fichier CHM ; PDF.

Installation de PhpDocumentor

  • Lire la documentation de PhpDocumentor
  • Récupérer l’archive de PhpDocumentor
  • Décompresser l’archive et déposer le dossier obtenu à la racine de son site

Corriger le nom des templates (tp au lieu de tpl)

Etrangement, les modèles, appelés template, fournis, ont parfois le suffixe tp au lieu de tpl. Ce qui génère de nombreuses erreurs du type : PHP Warning:  Smarty error: unable to read resource: "pkgelementindex.tpl" in...

Pour s’en débarrasser, il suffit de compléter le suffixe des fichiers tp.

Aller dans le dossier installé, puis dans le dossier phpDocumentor/Converters : cd phpDocumentor/Converters

Renommer tous les suffixes des fichiers tp en tpl, via une petite boucle du style :

for f in `find . -name '*.tp'`; do mv "${f}" "${f}l"; done

A voir également, les fichiers images avec extension .pn au lieu de .png.

for f in `find . -name '*.pn'`; do mv "${f}" "${f}g"; done

et css

for f in `find . -name '*.cs'`; do mv "${f}" "${f}s"; done

Usage de PhpDocumentor via l’interface web

  • Accéder à cette archive via un navigateur web (par exemple : http://localhost/PhpDocumentor
  • Dans le menu Files, indiquer le fichier à analyser dans le champ Files to parse. Si plusieurs fichiers sont concernés, séparer les noms d’une virgule ’,’. Si vous avez plusieurs fichiers dans un même dossier à traiter, compléter le champ Directory to parse
  • Dans le menu Output, indiquer dans Target le chemin où sera déposé le résultat. Si ce dossier de dépôt n’existe pas, il sera créé
  • Dans le menu Output, choisir le format de sortie (le style de pages HTML générées, ou document CHM, PDF).
  • Cliquer sur Create

Patienter. Patienter. C’est parfois long. Et parfois ça ne fonctionne pas, en général pour manque de mémoire allouée à PHP. Dans ce dernier cas, corriger la variable memory_limit de votre fichier php.ini.

En option, vous pouvez demander la recopie dans cette documentation des sources en mode colorisé via l’option Generate Highlighted Source Code du menu Options. Attention, les sources sont enrichis de code HTML verbeux qui multiplie la taille originale par 5, en moyenne.

Les scripts/fichiers PHP reconnus par PhpDocumentor

Sauf usage de Files to ignore du menu Files, tous les fichiers ayant un des suffixes (extension) suivants seront analysés :

  • php
  • php3
  • php4
  • phtml
  • inc

Ce sont ces types de fichier qui sont analysés par PhpDocumentor. Les autres types de fichier sont ignorés.

Pour ajouter d’autres extensions de fichier, compléter la constante de configuration _phpDocumentor_phpfile_exts du fichier phpDocumentor.ini.

Les formats de sortie proposés

Que l’on trouve dans le menu Output, HTML avec frames, sans frames (Smarty), et les formats PDF, CHM, ...

  • HTML:frames:default
  • HTML:frames:earthli
  • HTML:frames:l0l33t
  • HTML:frames:phpdoc.de
  • HTML:frames:phphtmllib
  • HTML:frames:phpedit
  • HTML:frames:DOM/default
  • HTML:frames:DOM/earthli
  • HTML:frames:DOM/l0l33t
  • HTML:frames:DOM/phpdoc.de
  • HTML:frames:DOM/phphtmllib
  • HTML:Smarty:default
  • HTML:Smarty:HandS
  • HTML:Smarty:PHP
  • PDF:default:default
  • CHM:default:default
  • XML:DocBook/peardoc2:default

Démonstration des formats sur http://manual.phpdoc.org/

A voir éventuellement :

Usage en ligne de commande

Plus rapide, mais nécessite la connaissance du terminal, du shell.

  • Ouvrir le terminal. Sur Mac : Applications, Utilitaires, Terminal.app
  • Aller dans le répertoire de PhpDocumentor (cd ...)
  • Donner les droits nécessaires au script shell phpdoc (chmod 755 par exemple)
  • Retirer les cr (carriage return, retours chariot du monde windows qui génèrent parfois des erreurs) dos2unix phpdoc
  • L’aide en ligne est disponible via ./phpdoc -h

Là aussi, parfois, ça ne fonctionne pas, en général pour manque de mémoire allouée à PHP. Dans ce dernier cas, corriger la variable memory_limit de votre fichier php.ini. Il est possible également de redéfinir cette valeur dans le script PHP phpdoc en insérant - par exemple - en début de script (aprés < ?php) ini_set(‘memory_limit’,’512M’) ; pour 512 Mo.

Exemple :

./phpdoc --directory /usr/local/sources \
   --target /usr/local/docs

En plus simple :

./phpdoc -d /usr/local/sources -t /usr/local/docs

Plussoyez !

Les forums sont fermés.