Générer une documentation navigable depuis les blocs PHPDoc d’une extension

$ phpdoc run -d src/ -t docs/ — une seule commande, et la documentation technique d’une extension, jusque-là éparpillée dans des commentaires PHPDoc plus ou moins consultés, devient un site HTML navigable, avec table des classes, index des fonctions et recherche intégrée. Ce tutoriel détaille la mise en place de ce générateur pour une extension métier de taille moyenne, sans plateforme de documentation lourde à héberger et à maintenir dans la durée.

Le contexte concret : une extension de gestion de stocks pour une coopérative viticole, développée par deux personnes, dont le code contient déjà des blocs PHPDoc réguliers sur les classes et méthodes principales, mais dont aucune documentation consultable n’existe en dehors du code source lui-même. L’objectif n’est pas de produire une documentation utilisateur final destinée aux exploitants du site, mais bien une documentation technique destinée aux développeurs qui interviennent sur le code.

Étape 1 : vérifier la qualité des blocs PHPDoc existants

Avant de générer quoi que ce soit, il faut s’assurer que les commentaires existants sont exploitables. Un bloc PHPDoc minimal mais correct suffit :

/**
 * Calcule le volume disponible pour un lot de vin donné.
 *
 * @param int $lot_id Identifiant du lot en base.
 * @param bool $inclure_reserve Si vrai, inclut le volume réservé.
 *
 * @return float Volume disponible exprimé en hectolitres.
 */
function stock_calculer_volume_disponible( $lot_id, $inclure_reserve = false ) {
    // ...
}

Les balises @param et @return sont celles qui apportent le plus de valeur au générateur : elles permettent de produire des signatures de fonction complètes et typées dans la documentation finale, sans effort supplémentaire au-delà de ce qui existe déjà dans un code bien commenté.

Étape 2 : installer phpDocumentor via Composer

phpDocumentor s’installe comme dépendance de développement, séparée du code de production livré au client, pour ne jamais alourdir l’extension elle-même.

$ composer require --dev phpdocumentor/phpdocumentor

Un fichier de configuration minimal, phpdoc.dist.xml, à la racine du projet, permet de restreindre l’analyse au dossier source utile et d’exclure les dépendances tierces déjà documentées ailleurs :

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor>
    <paths>
        <output>docs</output>
    </paths>
    <version number="1.0.0">
        <api>
            <source dsn=".">
                <path>src</path>
            </source>
            <ignore hidden="true">
                <path>vendor/**/*</path>
            </ignore>
        </api>
    </version>
</phpdocumentor>

Étape 3 : générer et consulter le site statique

La commande de génération produit un dossier docs/ entièrement statique, consultable localement dans un navigateur, sans serveur applicatif ni base de données.

$ vendor/bin/phpdoc run
$ php -S localhost:8080 -t docs/

Le résultat inclut une arborescence des espaces de noms, une liste des classes avec leurs méthodes documentées, et un moteur de recherche côté client qui fonctionne sans connexion réseau une fois le site généré. Pour une extension de taille moyenne, la génération complète prend généralement quelques secondes.

Étape 4 : intégrer la génération dans le flux de travail existant

Pour que cette documentation reste à jour, il est préférable de l’intégrer à un script déjà exécuté régulièrement, plutôt que de compter sur une régénération manuelle occasionnelle.

1. Ajouter un script Composer dédié, par exemple "docs": "phpdoc run", dans la section scripts du fichier composer.json.
2. Déclencher ce script lors de chaque montée de version publiée en interne, avant l’archivage de la nouvelle release.
3. Publier le dossier généré sur un espace de partage interne à l’agence, accessible aux développeurs concernés uniquement.

Ce que ce générateur ne couvre pas

La documentation produite ainsi reste strictement technique : elle décrit les classes, méthodes et fonctions telles qu’elles existent dans le code, avec leurs paramètres et types de retour. Elle ne remplace en rien une documentation utilisateur final, qui devrait plutôt expliquer comment configurer l’extension depuis l’interface d’administration, avec des captures d’écran et un vocabulaire non technique. Ces deux documentations répondent à des publics différents et gagnent à rester séparées.

• Documentation technique générée : destinée aux développeurs qui maintiennent ou étendent le code.
• Documentation utilisateur final : destinée aux exploitants du site, hors du périmètre de cet article.

Une documentation technique qui se régénère automatiquement à chaque version a plus de chances de rester exacte qu’un document Word maintenu manuellement à côté du code.

En résumé

Générer une documentation navigable à partir de blocs PHPDoc déjà présents ne demande ni plateforme lourde ni infrastructure dédiée : une dépendance Composer, un fichier de configuration minimal, et une commande suffisent. Le principal effort porte en amont, sur la qualité des commentaires déjà écrits dans le code, plutôt que sur l’outillage de génération lui-même.