Sami 项目使用文档

Sami 项目使用文档

1. 项目目录结构及介绍

Sami 项目的目录结构如下：

Sami/
├── CHANGELOG
├── LICENSE
├── README.rst
├── box.json
├── composer.json
├── composer.lock
├── phpunit.xml.dist
├── sami.php
├── examples/
│   ├── blackfire
│   ├── travis.ini
│   ├── .gitignore
│   ├── travis.yml
│   └── ...
└── ...

目录结构介绍

• CHANGELOG: 项目更新日志文件。
• LICENSE: 项目许可证文件。
• README.rst: 项目介绍和使用说明文件。
• box.json: Box 打包工具的配置文件。
• composer.json: Composer 依赖管理配置文件。
• composer.lock: Composer 锁定文件，记录当前依赖版本。
• phpunit.xml.dist: PHPUnit 测试配置文件。
• sami.php: Sami 配置文件，用于生成 API 文档。
• examples/: 示例目录，包含一些配置示例和测试文件。

2. 项目启动文件介绍

Sami 项目的启动文件是 sami.php。这个文件是 Sami 的配置文件，用于定义如何生成 API 文档。以下是 sami.php 的基本结构：

<?php

use Sami\Sami;
use Symfony\Component\Finder\Finder;

$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in('/path/to/symfony/src');

return new Sami($iterator, array(
    'theme'                => 'symfony',
    'title'                => 'Symfony2 API',
    'build_dir'            => __DIR__.'/build',
    'cache_dir'            => __DIR__.'/cache',
    'remote_repository'    => new GitHubRemoteRepository('username/repository', '/path/to/repository'),
    'default_opened_level' => 2,
));

启动文件介绍

• Finder: 使用 Symfony 的 Finder 组件来查找需要生成文档的 PHP 文件。
• Sami: 配置 Sami 生成文档的选项，如主题、标题、构建目录、缓存目录等。
• GitHubRemoteRepository: 配置远程仓库信息，用于生成文档中的链接。

3. 项目配置文件介绍

Sami 项目的配置文件主要是 sami.php，它定义了如何生成 API 文档。以下是配置文件的主要内容：

基本配置

return new Sami($iterator, array(
    'theme'                => 'symfony',
    'title'                => 'Symfony2 API',
    'build_dir'            => __DIR__.'/build',
    'cache_dir'            => __DIR__.'/cache',
    'remote_repository'    => new GitHubRemoteRepository('username/repository', '/path/to/repository'),
    'default_opened_level' => 2,
));

配置项介绍

• theme: 文档生成使用的主题，如 symfony。
• title: 生成的 API 文档的标题。
• build_dir: 文档生成后的输出目录。
• cache_dir: 缓存目录，用于存储生成的文档缓存。
• remote_repository: 远程仓库配置，用于生成文档中的链接。
• default_opened_level: 默认展开的文档层级。

通过这些配置，Sami 可以根据指定的代码目录生成相应的 API 文档。