README

警告：Sami不再受支持或维护。请随意分支。

对Sami生成的结果好奇？请查看 Symfony API。

安装

注意！

Sami需要 PHP 7。

使用composer安装：.. code-blok:: bash

$ composer require kml/sami

使用以下命令测试安装：.. code-blok:: bash

$ php ./vendor/kml/sami/sami.php

作为 phar文件 获取Sami

$ curl -O http://get.sensiolabs.org/sami.phar

通过执行不带任何参数的sami.phar文件来检查一切是否按预期工作

$ php sami.phar

注意

将Sami作为常规Composer依赖项安装不受支持。Sami是一个工具，不是一个库。因此，应将其作为独立包安装，以确保Sami的依赖项不会与您项目的依赖项冲突。

配置

在生成文档之前，您必须创建一个配置文件。以下是一个最简单的配置文件

<?php

return new Sami\Sami('/path/to/symfony/src');

配置文件必须返回一个Sami\Sami实例，构造函数的第一个参数是要为生成文档的代码的路径。

实际上，您可以使用任何有效的PHP迭代器（以及Symfony Finder类的任何实例）代替目录。

<?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);

Sami构造函数可以接受一个选项数组作为第二个参数

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,
));

以下是配置不同版本的方法

<?php

use Sami\Sami;
use Sami\RemoteRepository\GitHubRemoteRepository;
use Sami\Version\GitVersionCollection;
use Symfony\Component\Finder\Finder;

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

// generate documentation for all v2.0.* tags, the 2.0 branch, and the master one
$versions = GitVersionCollection::create($dir)
    ->addFromTags('v2.0.*')
    ->add('2.0', '2.0 branch')
    ->add('master', 'master branch')
;

return new Sami($iterator, array(
    'theme'                => 'symfony',
    'versions'             => $versions,
    'title'                => 'Symfony2 API',
    'build_dir'            => __DIR__.'/../build/sf2/%version%',
    'cache_dir'            => __DIR__.'/../cache/sf2/%version%',
    'remote_repository'    => new GitHubRemoteRepository('symfony/symfony', dirname($dir)),
    'default_opened_level' => 2,
));

要为PHP 5.2项目生成文档，只需将simulate_namespaces选项设置为true。

您可以在源代码的examples/目录下找到更多配置示例。

Sami仅记录公共API（公共属性和方法）；要更改此行为，请覆盖默认配置的filter。

<?php

use Sami\Parser\Filter\TrueFilter;

$sami = new Sami(...);
// document all methods and properties
$sami['filter'] = function () {
    return new TrueFilter();
};

渲染

现在我们有了配置文件，让我们生成API文档

$ php sami.phar update /path/to/config.php

生成的文档可以在配置的build/目录下找到（注意：由于JavaScript执行限制，客户端搜索引擎在Chrome中不工作，除非Chrome以"--allow-file-access-from-files"选项启动--它在Firefox中运行良好）。

默认情况下，Sami配置为在“增量”模式下运行。这意味着当运行update命令时，Sami只会重新生成自上次执行以来代码中发生更改所需更新的文件。

Sami还可以检测您的phpdoc中的问题，并且如果您添加了-v选项，它还可以告诉您需要修复的内容。

$ php sami.phar update /path/to/config.php -v

创建一个主题

如果默认主题不满足您的需求，您可以非常容易地创建一个新的主题，或者只是覆盖现有的一个。

主题只是一个包含描述主题的manifest.yml文件的目录（这是一个YAML文件）

name:   symfony
parent: default

上面的配置创建了一个基于内置的default主题的新symfony主题。要覆盖模板，只需创建一个与原始文件同名的新文件。例如，以下是如何扩展默认类模板，以便在类页面标题中将类名前缀为“Class ”

{# pages/class.twig #}

{% extends 'default/pages/class.twig' %}

{% block title %}Class {{ parent() }}{% endblock %}

如果您熟悉Twig，您将能够非常容易地调整模板的各个方面，因为所有内容都已被很好地隔离在命名的Twig块中。

主题还可以添加更多模板和静态文件。以下是默认主题的清单

name: default

static:
    'css/sami.css': 'css/sami.css'
    'css/bootstrap.min.css': 'css/bootstrap.min.css'
    'css/bootstrap-theme.min.css': 'css/bootstrap-theme.min.css'
    'fonts/glyphicons-halflings-regular.eot': 'fonts/glyphicons-halflings-regular.eot'
    'fonts/glyphicons-halflings-regular.svg': 'fonts/glyphicons-halflings-regular.svg'
    'fonts/glyphicons-halflings-regular.ttf': 'fonts/glyphicons-halflings-regular.ttf'
    'fonts/glyphicons-halflings-regular.woff': 'fonts/glyphicons-halflings-regular.woff'
    'js/bootstrap.min.js': 'js/bootstrap.min.js'
    'js/jquery-1.11.1.min.js': 'js/jquery-1.11.1.min.js'
    'js/handlebars.min.js': 'js/handlebars.min.js'
    'js/typeahead.min.js': 'js/typeahead.min.js'

global:
    'index.twig':      'index.html'
    'doc-index.twig':  'doc-index.html'
    'namespaces.twig': 'namespaces.html'
    'classes.twig':    'classes.html'
    'interfaces.twig': 'interfaces.html'
    'traits.twig':     'traits.html'
    'opensearch.twig': 'opensearch.xml'
    'search.twig':     'search.html'
    'sami.js.twig':    'sami.js'

namespace:
    'namespace.twig': '%s.html'

class:
    'class.twig': '%s.html'

文件包含在部分中，这取决于Sami如何处理它们

• static：文件按原样复制（如图像、样式表或JavaScript文件等资产）；
• global：不依赖于当前类上下文的模板；
• namespace：为每个命名空间应生成的模板；
• class：为每个类应生成的模板。

搜索索引

Sami的自动完成和搜索功能通过一个基于项目类、命名空间、接口和特性生成的搜索索引提供。您可以通过重写sami.js.twig中的search_index_extra块来自定义搜索索引。

search_index_extra允许您扩展默认主题并向索引添加更多条目。例如，某些项目实现了在运行时动态生成的魔术方法。您可能希望在生成API文档时记录这些方法并将它们添加到搜索索引中。

搜索索引中的每个条目都是一个包含以下键的JavaScript对象

类型

与条目关联的类型。内置类型为“类”、“命名空间”、“接口”、“特性”。您可以添加特定于应用程序的附加类型，并且类型信息将显示在搜索结果旁边。

名称

条目的名称。这是索引中可搜索的元素（例如，类名、命名空间名等）。

fromName

元素的父元素（如果有）。这可以用于为条目提供上下文。例如，类的fromName将是类的命名空间。

fromLink

条目父元素的链接（如果有）。这用于将子元素链接到父元素。例如，这将是从类到类命名空间的链接。

doc

条目的简短文本描述。

覆盖索引的一个示例可能是记录动态生成的Web服务客户端的API操作。以下是一个简单的示例，该示例将动态生成的Web服务客户端的API操作添加到搜索索引中

{% extends "default/sami.js.twig" %}

{% block search_index_extra %}
    {% for operation in operations -%}
        {"type": "Operation", "link": "{{ operation.path }}", "name": "{{ operation.name }}", "doc": "{{ operation.doc }}"},
    {%- endfor %}
{% endblock %}

此示例假设模板中有一个名为operations的变量，该变量包含一个操作数组。

注意

为索引中添加的每个条目始终包含一个尾随逗号。Sami将负责确保正确处理尾随逗号。