SAMIでPHPドキュメントを生成します

sami：php

の強力なAPIドキュメントジェネレーター

PHPメソッド、クラス、および機能の個別のドキュメントを生成することは、ベストプラクティスです。 この記事では、このプロセスを簡素化し、読みやすさとアクセシビリティを向上させる堅牢なAPIドキュメントジェネレーターであるSamiを紹介します。

samiの重要な機能：

PHPコードのスタンドアロンドキュメントを生成し、ソースコードを直接ナビゲートする必要性を排除します。
• Phar ArchiveまたはComposerを介した簡単なインストール。
• PHP構成ファイルを介して高度に構成でき、テーマ、タイトル、ビルドディレクトリ、キャッシュのカスタマイズを許可します。
カスタムテーマとアセットインクルージョンは、パーソナライズされたルックアンドフィールのためにサポートしています。
• gitバージョン制御と統合され、複数のコードベースバージョンのドキュメントを有効にします。
• docblocksを理解する：

docblocksはsamiに不可欠です。それらは、クラス、インターフェイス、方法、または属性定義の上に配置されたマルチラインコメントです。 Laravelの例は次のとおりです

docblocksはで始まり、

で終了し、各ラインは

で始まります。

や

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

などの注釈は、追加情報を提供します。 phpdocumentorの注釈基準は広くサポートされています

/**sami vs.その他のジェネレーター：*/ * @param他のジェネレーターが存在しますが（例：PhpDocumentor）、SamiはGitHubの統合と小枝のテンプレート機能のために際立っています。 @var

samiのインストール：

これらのメソッドのいずれかを選択します：

Phar Archive：をダウンロードして。

を実行します

Composer：

を使用して、Samiをプロジェクトに追加します。 次に、。を実行します sami.phar php sami.phar

laravelドキュメントの生成（例）：composer require sami/sami:3.0.*php vendor/sami/sami/sami.php

Laravel Frameworkをクローンする：

ファイルを作成します（下の構成セクションを参照）。

run：

1. git clone git@github.com:laravel/framework.git docs構成（
）：
2. config/config.php
このファイルは、
3. インスタンスを返します：php vendor/sami/sami/sami.php update config/config.php
updateコマンドを実行した後、PHPサーバー（

）を起動し、

。でドキュメントにアクセスします。 config/config.php

gitバージョン：

Samiは、複数のGITバージョンの取り扱いに優れています。 構成にversionsオプションを追加します：

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

%version%inbuild_dirとcache_dir。

に含めることを忘れないでください

カスタムテーマの作成：

SAMIは、カスタムテーマを作成できます。 テーマディレクトリ（例：manifest.yml）に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;

次に、base.twigテンプレートを変更してCSSを含めます。カスタムテーマを使用するには、構成ファイルを更新します：'theme' => 'mytheme'。 ドキュメントを再生するには、sami render config/config.php --forceを実行してください。

結論：

SAMIは、PHPプロジェクトの高品質のAPIドキュメントを生成するための強力で柔軟なソリューションを提供します。 Gitバージョンやカスタムテーマサポートなどの機能は、PHP開発者にとって貴重なツールになります。 完全な例はGitHubで入手できます（この例でGitHubリポジトリが存在する場合は、ここにリンクが追加されます）。

以上がSAMIでPHPドキュメントを生成しますの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。