Générer la documentation d'un projet PHP

Vous avez un projet PHP et vous souhaitez — hop, hop, en deux temps trois mouvements — générer un site de documentation sans vous prendre la tête.

Facile ! phpDocumentor le fait pour vous et, comme une image Docker existe, presque tout tient en une seule commande.

Une commande, un site de documentation complet​

Depuis la racine de votre projet PHP, lancez :

$ docker run -it --rm -u $(id -u):$(id -g) -v .:/data phpdoc/phpdoc:3▋

Et voici ce qui atterrit dans le dossier .phpdoc — celui-ci a été généré à partir du code de WordPress :

Un site navigable avec les namespaces, les classes, leurs méthodes et les docblocks que vous avez écrits. Rien n'a été installé sur votre machine : phpDocumentor, PHP et toutes les dépendances vivent dans l'image, qui disparaît avec le container grâce à --rm.

Le fichier de configuration​

phpDocumentor a besoin d'un fichier de configuration pour savoir quoi analyser et où écrire. Créez un nouveau fichier appelé phpdoc.xml avec ce contenu, dans le répertoire de votre projet :

<?xml version="1.0" encoding="UTF-8"?>
<phpdocumentor
    configVersion="3"?
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"?
    xmlns="https://www.phpdoc.org"
    xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd"?
>
    <paths>
        <output>./.phpdoc</output>
        <cache>/tmp/phpdoc</cache>
    </paths>
    <version number="3.0.0">
        <api>
            <source dsn=".">?
                <path>src/</path>
            </source>
        </api>
    </version>
</phpdocumentor>

C'est ce qui indique à la commande ci-dessus d'analyser le dossier src et de créer le répertoire .phpdoc où la documentation sera enregistrée.

Conclusion​

Un docker run, un fichier XML, et n'importe quel projet PHP — le vôtre, ou celui dont vous venez d'hériter — devient un site de documentation navigable. Le plus intéressant n'est pas la génération elle-même : c'est que la qualité de la sortie reflète directement les docblocks présents dans le code. Lancez-la une fois sur un projet et vous voyez immédiatement où l'effort de documentation est réellement passé.

Bash n'a pas d'équivalent à phpDocumentor, c'est pourquoi j'ai écrit le mien ; voyez Linux - Générer de la documentation à partir de scripts Bash. Et pour de la documentation qui n'est pas extraite du code du tout, il y a Quarto - Comment j'ai construit un écosystème auto-documenté pour plus de 50 projets.