README

警告: SamI 不再受到支持或维护。请随意fork。

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

安装

注意！

SamI 需要 PHP 7。

将SamI作为 phar文件 获取

$ 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对象

type

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

name

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

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将确保正确处理尾随逗号。