Génération de la documentation PHP avec Sami

Sami: un puissant générateur de documentation API pour php

Générer une documentation distincte pour vos méthodes, classes et fonctions PHP est une meilleure pratique. Cet article présente Sami, un générateur de documentation API robuste qui simplifie ce processus, améliorant la lisibilité et l'accessibilité.

Caractéristiques clés de Sami:

• génère une documentation autonome pour le code PHP, éliminant la nécessité de naviguer directement au code source.
• Installation facile via des archives de phar ou du compositeur.
• hautement configurable via un fichier de configuration PHP, permettant la personnalisation des thèmes, des titres, des répertoires de construction et de la mise en cache.
• prend en charge les thèmes personnalisés et l'inclusion des actifs pour un aspect et une sensation personnalisés.
• s'intègre au contrôle de la version git, permettant une documentation pour plusieurs versions de base de code.

Comprendre les docblocks:

Les docblocks sont essentiels pour Sami. Ce sont des commentaires multi-lignes placés au-dessus des définitions de classe, d'interface, de méthode ou d'attribut. Voici un exemple de Laravel:

abstract class Manager
{
    /**
     * The application instance.
     *
     * @var \Illuminate\Foundation\Application
     */
    protected $app;

    /**
     * Create a new manager instance.
     *
     * @param \Illuminate\Foundation\Application $app
     * @return void
     */
    public function __construct($app)
    {
        $this->app = $app;
    }
}

docblocks commencent par /**, finissent par */, et chaque ligne à l'intérieur commence par *. Des annotations comme @param et @var fournissent des informations supplémentaires. Les normes d'annotation de PhpDocumentor sont largement prises en charge.

Sami vs autres générateurs:

Alors que d'autres générateurs existent (par exemple, phpDocumentor), Sami se démarque en raison de son intégration GitHub et de ses capacités de modèles de brindilles.

Installation de Sami:

Choisissez l'une de ces méthodes:

1. PHAR ARCHIVE: Télécharger sami.phar et exécuter php sami.phar.
2. Composer: Utilisez composer require sami/sami:3.0.* pour ajouter Sami à votre projet. Puis exécutez php vendor/sami/sami/sami.php.

Génération de la documentation de Laravel (exemple):

1. Clone Le framework Laravel: git clone git@github.com:laravel/framework.git docs
2. Créer un fichier config/config.php (voir la section de configuration ci-dessous).
3. Run: php vendor/sami/sami/sami.php update config/config.php

Configuration (config/config.php):

Ce fichier renvoie une instance SamiSami:

$dir = __DIR__ . '/../docs';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

$options = [
    'theme'                => 'default',
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel',
    'cache_dir'            => __DIR__ . '/../cache/laravel',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;

Après avoir exécuté la commande de mise à jour, démarrez un serveur PHP (php -S localhost:8000 -t build/) et accédez à la documentation à http://localhost:8000/laravel/.

Git Versioning:

Sami excelle à gérer plusieurs versions GIT. Ajoutez l'option versions à votre configuration:

abstract class Manager
{
    /**
     * The application instance.
     *
     * @var \Illuminate\Foundation\Application
     */
    protected $app;

    /**
     * Create a new manager instance.
     *
     * @param \Illuminate\Foundation\Application $app
     * @return void
     */
    public function __construct($app)
    {
        $this->app = $app;
    }
}

N'oubliez pas d'inclure %version% dans build_dir et cache_dir.

Création de thèmes personnalisés:

Sami permet de créer des thèmes personnalisés. Placez un fichier manifest.yml dans votre répertoire de thème (par exemple, themes/mytheme/manifest.yml):

$dir = __DIR__ . '/../docs';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

$options = [
    'theme'                => 'default',
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel',
    'cache_dir'            => __DIR__ . '/../cache/laravel',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;

Ensuite, modifiez le modèle base.twig pour inclure votre CSS. Mettez à jour votre fichier de configuration pour utiliser votre thème personnalisé: 'theme' => 'mytheme'. Exécutez sami render config/config.php --force pour régénérer la documentation.

Conclusion:

Sami propose une solution puissante et flexible pour générer une documentation API de haute qualité pour vos projets PHP. Ses fonctionnalités, y compris le versioning GIT et la prise en charge du thème personnalisé, en font un outil précieux pour tout développeur PHP. L'exemple complet est disponible sur github (un lien serait ajouté ici si un repo github existait pour cet exemple).

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!