phpDocumentor
v3.5.3
phpDocumentor est l'outil de documentation de facto pour les projets PHP, offrant une solution robuste pour générer une documentation complète sans effort. En analysant votre code source PHP et les commentaires DocBlock, phpDocumentor génère un ensemble complet de documentation API, ce qui en fait un outil indispensable pour les développeurs recherchant des bases de code claires et bien documentées.
Au-delà de ses prouesses en matière de documentation API, phpDocumentor va plus loin en apportant des fonctionnalités supplémentaires. Il est doté de la possibilité de créer des diagrammes UML, ce qui en fait un outil polyvalent pour visualiser la structure du code. De plus, phpDocumentor propose un analyseur de langage de balisage complet, prenant en charge à la fois la syntaxe RestructuredText et Markdown. Cette flexibilité vous permet de documenter votre projet en utilisant le langage de balisage qui correspond le mieux à vos préférences.
Une fonctionnalité notable de phpDocumentor est sa capacité à inclure des parties de votre documentation API directement dans votre documentation RestructuredText. Cette intégration garantit que votre documentation et votre code restent synchronisés, ce qui vous permet d'économiser du temps et des efforts pour maintenir une documentation de projet précise et à jour.
Inspiré par ses prédécesseurs, phpDocumentor 1 et JavaDoc, phpDocumentor continue d'innover, en restant à jour avec les dernières technologies et fonctionnalités du langage PHP. Cet engagement garantit que les développeurs ont accès à la meilleure expérience de documentation possible, conforme aux pratiques de développement modernes.
Dans ce guide, nous explorerons les différentes fonctionnalités de phpDocumentor, depuis sa fonctionnalité de base de génération de documentation API jusqu'à ses capacités avancées d'analyse des langages de balisage. Que vous soyez débutant ou développeur expérimenté, phpDocumentor est votre allié pour créer des projets PHP bien documentés, maintenables et compréhensibles.
La v3 est la dernière version stable.
Pour des informations plus détaillées, vous pouvez consulter notre documentation en ligne sur https://docs.phpdoc.org/.
phpDocumentor prend en charge les éléments suivants :
Compatible PHP 7.0+ , prise en charge complète des espaces de noms, des fermetures et bien plus encore.
Docblock plutôt que les types , les docblocks peuvent être plus explicites sur les types, tous les formats ne sont pas pris en charge par PHP natif.
Affiche n'importe quelle balise , certaines balises ajoutent des fonctionnalités supplémentaires à phpDocumentor (telles que @link).
Faible utilisation de la mémoire , l'utilisation maximale de la mémoire pour les petits projets est inférieure à 20 Mo, les projets moyens à 40 Mo et les grands frameworks à 100 Mo.
Analyse incrémentielle , si vous avez conservé le fichier de structure d'une exécution précédente, vous obtenez une amélioration supplémentaire des performances allant jusqu'à 80 % en plus de l'augmentation de la vitesse de traitement mentionnée ci-dessus.
Création de modèles facile , si vous souhaitez créer une image de marque, il vous suffit d'appeler 1 tâche et de modifier 3 fichiers.
Processus en deux étapes , phpDocumentor génère d'abord un cache avec la structure de votre application avant de créer la sortie. Si vous le souhaitez, vous pouvez l'utiliser pour alimenter vos propres outils ou formateurs !
La prise en charge des génériques , avec une analyse plus statique dans les types PHP, est devenue plus complexe. phpDocumentor comprend ces types. Et les rendra comme des types de première classe.
PhpDocumentor nécessite PHP 8.1 ou supérieur pour fonctionner. Cependant, le code des versions antérieures de PHP peut être analysé.
Tous les modèles fournis avec phpDocumentor prennent en charge les diagrammes de classes basés sur la base de code lu. Cela nécessitera que l'application [PlantUml] soit installée sur la machine exécutant phpDocumentor. Le rendu des diagrammes de classes à l'aide de [PlantUml] est facultatif et les avertissements concernant l'absence de [PlantUml] peuvent être ignorés. Cependant, votre documentation contiendra des liens morts dans ce cas. Le diagramme de classes sera créé avec l'option --setting=graphs.enabled=true .
Il existe 4 façons d'installer phpDocumentor :
Utiliser phive (recommandé)
Utilisation du PHAR (installation manuelle)
Via Docker
Via Compositeur
$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42
Pour plus d’informations sur phive, consultez leur site Web. Maintenant que phpDocumentor est installé, il peut être exécuté comme ceci :
php tools/phpDocumentor
Téléchargez le fichier phar depuis https://github.com/phpDocumentor/phpDocumentor/releases
Vous pouvez exécuter le phar comme ceci : php phpDocumentor.phar
$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc
Mais attends ? Et le compositeur ?
Ah, vous avez découvert notre secret. Il existe un package phpdocumentor composer que vous pouvez utiliser pour installer phpDocumentor.
Cependant : phpDocumentor est une application complexe, et ses bibliothèques sont utilisées dans d'innombrables autres bibliothèques et applications (2 de nos bibliothèques ont chacune plus de 150 millions de téléchargements) ; et cela signifie que les chances d'un conflit entre l'une de nos dépendances et la vôtre sont élevées. Et quand je dis haut, c’est vraiment haut.
Donc, à cause de ce qui précède : nous n'approuvons ni ne soutenons activement l'installation de phpDocumentor à l'aide de Composer.
Le moyen le plus simple d'exécuter phpDocumentor consiste à exécuter la commande suivante :
$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>
Cette commande analysera le code source fourni à l'aide de l'argument -d et le sortira dans le dossier indiqué par l'argument -t .
phpDocumentor prend en charge toute une gamme d'options pour configurer la sortie de votre documentation. Vous pouvez exécuter la commande suivante ou consulter notre site Web pour une liste plus détaillée des options de ligne de commande disponibles.
$ phpdoc run -h
phpDocumentor prend également en charge l'utilisation de fichiers de configuration (nommés phpdoc.xml ou phpdoc.dist.xml par défaut). Veuillez consulter la documentation pour voir le format et les options prises en charge.
PhpDocumentor n'a pas de versions nocturnes. Cependant, lors de chaque pipeline, un artefact phar est construit. Si vous souhaitez tester la version avant-gardiste de phpDocumentor, jetez un œil dans la section actions de ce référentiel. Chaque flux de travail d'assurance qualité réussi comporte une section Artefacts en bas avec l'artefact phar construit.
Nous contacter est simple et peut se faire avec :
Twitter : @phpDocumentor
Site Web : https://www.phpdoc.org
GitHub : https://www.github.com/phpDocumentor/phpDocumentor
Courriel : [email protected]
