README

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

对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 主题。要覆盖模板，只需创建一个与原始文件同名的新文件。例如，以下是扩展默认类模板以在类页面标题中前缀类名的示例

{# 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

与条目关联的类型。内置类型有"Class"（类）、"Namespace"（命名空间）、"Interface"（接口）、"Trait"（特性）。您可以添加特定于应用程序的额外类型，类型信息将显示在搜索结果旁边。

name

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

fromName

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

fromLink

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

doc

条目的简短文本描述。

当覆盖索引时，有用的一个例子可能是记录网络服务客户端动态生成的API操作。以下是一个简单示例，它将网络服务客户端的动态生成的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将负责正确处理尾随逗号。