Generierung von PHP -Dokumentation mit Sami

sami: ein leistungsstarker API -Dokumentationsgenerator für PHP

Eine separate Dokumentation für Ihre PHP -Methoden, Klassen und Funktionen generieren, ist eine bewährte Verfahren. In diesem Artikel wird Sami vorgestellt, einen robusten API -Dokumentationsgenerator, der diesen Prozess vereinfacht und die Lesbarkeit und Zugänglichkeit verbessert.

Schlüsselmerkmale von Sami:

• generiert eine eigenständige Dokumentation für den PHP -Code und beseitigt die Notwendigkeit, den Quellcode direkt zu navigieren.
• Einfache Installation über Phar -Archiv oder Komponist.
• hochkonfigurierbar über eine PHP -Konfigurationsdatei, die die Anpassung von Themen, Titeln, Erstellen von Verzeichnissen und Caching ermöglicht.
• unterstützt benutzerdefinierte Themen und Einbeziehung von Asset für ein personalisiertes Erscheinungsbild.
• Integriert sich in die Git -Versionskontrolle und aktiviert die Dokumentation für mehrere Codebasis -Versionen.

DocBlocks verstehen:

docblocks sind für sami unerlässlich. Es sind mehrzeilige Kommentare, die oben über den Klassen-, Schnittstellen-, Methoden- oder Attributdefinitionen platziert sind. Hier ist ein Laravel -Beispiel:

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 beginnen mit /**, enden mit */ und jede Zeile in innerhalb von beginnt mit *. Anmerkungen wie @param und @var geben zusätzliche Informationen an. Die Annotationsstandards von PHPDocumentor werden weithin unterstützt.

sami gegen andere Generatoren:

Während andere Generatoren existieren (z. B. phpdocumentor), sticht Sami aufgrund seiner Github -Integration und der Zweig -Templating -Funktionen auf.

sami installieren:

Wählen Sie eine dieser Methoden:

1. Phar Archiv: herunterladen sami.phar und run php sami.phar.
2. Komponist: Verwenden Sie composer require sami/sami:3.0.*, um Sami zu Ihrem Projekt hinzuzufügen. Dann führen Sie php vendor/sami/sami/sami.php.
aus

Laravel -Dokumentation (Beispiel) erzeugen:

1. Klon das Laravel -Framework: git clone git@github.com:laravel/framework.git docs
2. Erstellen Sie eine config/config.php Datei (siehe Abschnitt Konfiguration unten).
3. run: php vendor/sami/sami/sami.php update config/config.php

Konfiguration (config/config.php):

Diese Datei gibt eine SamiSami Instanz zurück:

$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;

Starten Sie nach dem Ausführen des Aktualisierungsbefehls einen PHP -Server (php -S localhost:8000 -t build/) und greifen Sie auf die Dokumentation unter http://localhost:8000/laravel/ zu.

Git Versioning:

Sami zeichnet mehrere Git -Versionen ab. Fügen Sie der Option versions Ihrer Konfiguration hinzu:

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;
    }
}

Denken Sie daran, %version% in build_dir und cache_dir zu enthalten.

Erstellen benutzerdefinierter Themen:

Sami ermöglicht das Erstellen von benutzerdefinierten Themen. Platzieren Sie eine manifest.yml -Datei in Ihr Themenverzeichnis (z. B. 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;

Ändern Sie dann die base.twig -Schamplate, um Ihre CSS einzuschließen. Aktualisieren Sie Ihre Konfigurationsdatei, um Ihr benutzerdefiniertes Thema zu verwenden: 'theme' => 'mytheme'. Führen Sie sami render config/config.php --force aus, um die Dokumentation zu regenerieren.

Schlussfolgerung:

sami bietet eine leistungsstarke und flexible Lösung für die Erzeugung hochwertiger API-Dokumentation für Ihre PHP-Projekte. Die Funktionen, einschließlich Git -Versioning und benutzerdefinierter Themenunterstützung, machen es zu einem wertvollen Tool für jeden PHP -Entwickler. Das vollständige Beispiel ist auf GitHub verfügbar (Link wird hier hinzugefügt, wenn ein Github -Repo für dieses Beispiel vorhanden wäre).

Das obige ist der detaillierte Inhalt vonGenerierung von PHP -Dokumentation mit Sami. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!