用萨米生成PHP文档

sami：一个强大的API文档生成器，用于PHP

>为您的PHP方法，类和功能生成单独的文档是最佳实践。 本文介绍了SAMI，这是一个强大的API文档生成器，可简化此过程，改善可读性和可访问性。

> sami的关键特征：

>

生成用于PHP代码的独立文档，消除了直接导航源代码的需求。

>通过Phar Archive或Composer轻松安装。
• 通过PHP配置文件高度配置，允许自定义主题，标题，构建目录和缓存。
• 支持自定义主题和资产包含，以获得个性化的外观。
与Git版本控件集成，为多个代码库版本启用文档。
• 理解docblocks：
对萨米人至关重要。它们是将类，接口，方法或属性定义放置的多行注释。 这是一个laravel示例：

> dicblocks以开头，以

结尾，而内的每一行均以

开始。

和

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> @var虽然存在其他发电机（例如，phpdocumentor），但由于其github集成和twig模板能力而脱颖而出。

>

>安装sami：>

选择以下方法之一：

PHAR档案：下载

和运行​​

。

>。

>
1. > Composer：>使用将SAMI添加到您的项目中。 然后运行sami.phar。php sami.phar
2. composer require sami/sami:3.0.*php vendor/sami/sami/sami.php生成Laravel文档（示例）：
>

克隆laravel框架：

>

创建一个文件（请参阅下面的配置部分）。>

>运行：

1. git clone git@github.com:laravel/framework.git docs
2. configuration（config/config.php）：
3. 此文件返回aphp vendor/sami/sami/sami.php update config/config.php实例：

运行更新命令后，启动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%>中包括build_dir。 cache_dir

创建自定义主题：

SAMI允许创建自定义主题。 将一个文件放在主题目录中（例如

）：>

然后，修改manifest.yml模板以包含您的CSS。更新您的配置文件以使用您的自定义主题：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 'theme' => 'mytheme' sami render config/config.php --force

结论：

Sami提供了一种强大而灵活的解决方案，用于为您的PHP项目生成高质量的API文档。 它的功能，包括GIT版本控制和自定义主题支持，使其成为任何PHP开发人员的宝贵工具。 完整的示例可在GitHub上找到（如果为此示例存在GitHub存储库，则可以在此处添加链接）。

以上是用萨米生成PHP文档的详细内容。更多信息请关注PHP中文网其他相关文章！