Générez votre documentation PHP facilement

Génération de documentation PHP avec PHPDocumentor

Voyons cette semaine comment générer une documentation avec PHPDocumentor, que ce soit pour simplifier le partage de vos API ou faciliter la maintenance de vos applications.

PHPDocumentor

PHPDocumentor est un outil écrit en PHP qui analyse votre code (en PHP aussi) pour rassembler les blocs de documentation et en faire une documentation sous la forme de pages HTML.

Vous pouvez trouver un exemple de documentation générée avec PHPDocumentor sur le site.

Il peut être intégré à un projet, comme dépendance de développement ou être installé à part, en mode standalone, pour être capable d’analyser n’importe quel code source présent sur votre environnement de développement. C’est cette dernière méthode que nous allons détailler ici.

Les fonctions, classes, variables, … sont récupérées automatiquement, et agrémentées de leur description présente dans les blocs de documentation.

Un exemple de bloc de documentation :

/**
 * Fonction qui dit bonjour
 *
 * Cette fonction dit bonjour. Si l'utilisateur n'a pas indiqué son nom,
 * la valeur par défaut est "world".
 * @param string $name Le nom de l'utilisateur
 * @return string Une phrase saluant l'utilisateur
 */
function hello($name = "world") {
	return "hello " . $name . " !";
}
Exemple de documentation de code PHP

Pour chaque fichier, classe, … il est aussi possible d’ajouter des exemples et des liens externes.

Installation

Téléchargez d’abord l’archive contenant la dernière version de PHPDocumentor (pas la version Source code).

Décompressez l’archive où bon vous semble. C’est tout.

Génération de la documentation

En ligne de commande

Dans une console permettant la ligne de commande, saisissez :

php "C:\Applications\phpDocumentor\bin\phpdoc.php"

Si le binaire de PHP n’est pas dans la variable système, vous pouvez toujours indiquer le chemin complet vers celui-ci.

Depuis Brackets

Pour démarrer la génération automatique depuis Brackets, il suffit d’ajouter une commande pour démarrer PHPDocumentor avec l’extension Command Runner dont j’avais déjà parlé.

[
  {
    "label": "Générer la documentation",
    "cmd": "php 'C:\Applications\phpDocumentor\bin\phpdoc.php'",
    "key": "F4",
    "args": []
  }
]
Documenter avec Command Runner

Avec cmder

Si vous utilisez cmder, l’excellent substitut à l’invite de ligne de commande de Windows (si vous utilisez un autre système d’exploitation, vous n’avez certainement pas besoin de  substitut), vous pouvez créer un alias pour PHPDocumentor.

Pour cela, ajoutez cet alias dans le fichier cmder/config/aliases :

phpdoc=php "C:\Applications\phpDocumentor\bin\phpdoc.php"

Pour générer une documentation, il suffit de vous rendre dans le dossier contenant les sources et de saisir phpdoc.

Une petite parenthèse : si vous utilisez à la fois Brackets et cmder, il existe une extension pour Brackets permettant d’ouvrir le dossier du projet en cours dans cmder. Et l’auteur est tellement talentueux. Euh oui j’arrête.

Configuration de PHPDocumentor

Vous pouvez indiquer les paramètres de génération de la documentation à la ligne de commande. Si ce n’est pas le cas, ils sont lus automatiquement depuis les fichiers de configuration globaux et par projet.

Configuration par projet

Vous pouvez également configurer le comportement de PHPDocumentor directement dans le dossier du projet. Pour cela, il suffit d’y créer un fichier phpdoc.xml :

<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
	<parser>
		<target>documentation</target>
	</parser>
	<transformer>
		<target>documentation</target>
	</transformer>
	<transformations>
		<template name="clean" />
	</transformations>
	<files>
		<directory>.</directory>
		<ignore>documentation/*</ignore>
	</files>
</phpdoc>
Exemple de configuration de phpDocumentor

Le rôle de cette configuration est de créer un dossier documentation dans le dossier du code PHP pour y écrire la documentation.

Ce fichier peut être versionné, sur git par exemple. Le dossier de documentation peut être exclu en l’ajoutant au fichier .gitignore.

Le mot de la fin

Même si ce n’est pas forcément pour générer une documentation, documentez bien votre code.

Cet article vous a été utile ? Partage it !

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Si vous le souhaitez, renseignez le champ 'Nom' de cette façon : 'VotreNom@VotreMotClef' pour obtenir une ancre optimisée pour les moteurs de recherche.