[译] 使用 Sami 生成 PHP 文档

原文地址: Generating PHP Documentation with Sami

为方法, 类, 函数生成文档已经成为了程序员的习惯, 因此须要知道经过源代码生成独立的文档. 本文中我会介绍 Sami, 一款 新的 API 文档生成工具.

什么是 DocBlock?

DocBlock 是插入到 类, 接口, 方法, 属性顶部的多行注释, 为了阐明这个, 咱们看下 Laravel 中的代码片断

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;
  }
}

DocBlock 开始于 /**, 结束于 */, 每行之间使用 *. 当定义一个类属性或者方法的时候, 咱们会写一个描述或者多个注释来描述这个功能. 在这些示例中 @param 和@var 会被用到. 你能够访问 phpDocumentor 官方网站来熟悉每一个标签的用法.

API 文档生成器

世界上充满许多文档生成器, 可是最好的一个是 phpDocumentor, 我喜欢 Sami 的主要缘由是可以使用github 上版本控制的文档, 而且可使用 Twig 来生成模版

安装 Sami

有两种方式来安装 Sami. 第一个是 下载 Phar 压缩包而且使用php来运行

php sami.phar

第二个方式是经过 Composer. 你能够运行 composer require sami/sami:3.0.* 命令来添加 sami 包到你的项目中.

php vendor/sami/sami/sami.php

复制 Laravel’s 文档

本示例中, 我会生成 Laravel Illuminate package 的文档

git clone git@github.com:laravel/framework.git docs

如今咱们的文件结构以下所示:

docs/
vendor/
composer.json

update 命令用来更新文档, 下面是使用方法:

php vendor/sami/sami/sami.php update config/config.php

config.php 文件来描述你的文档结构而且告知如何渲染输出.

Configuration / 配置

配置文件必须返回 Sami\Sami 实例, 他接受 Symfony\Component\Finder\Finder 实例和一系列的选择项.

// config/config.php
    
$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;

$dir 变量保存源代码的路径. $iterator 获取全部文件而且选择 *.php 而且排除 build 和test 目录. $options 变量里边的内容比较显而易见. theme设置成 default , 咱们稍后讲如何创建本身的主题. build_dir 保存输出文件. cache_dir 放置 Twig 缓存, title 是生成文档的标题

如今, 打开命令行并运行以下命令

php vendor/sami/sami/sami.php update config/config.php

命令执行完以后, 你能够运行内置的PHP服务器来查看文档, 运行 php -S localhost:8000 -t build/, 而且访问 http://localhost:8000/laravel/ 来查看运行结果

使用 Git 版本控制

我提到了使用 Sami 的一个重要缘由就是他的版本控制. options['versions'] 参数接受一个 Sami\Version\GitVersionCollection 实例来保存你的 Git 库配置. 以下, 让咱们建立 5.0 和4.2 分支的文档.

$dir = __DIR__ . '/../docs/src';

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->in($dir);

$versions = Sami\Version\GitVersionCollection::create($dir)
    ->add('5.0', 'Master')
    ->add('4.2', '4.2');


$options = [
    'theme'                => 'default',
    'versions'             => $versions,
    'title'                => 'Laravel API Documentation',
    'build_dir'            => __DIR__ . '/../build/laravel/%version%',
    'cache_dir'            => __DIR__ . '/../cache/laravel/%version%',
];

$sami = new Sami\Sami($iterator, $options);

return $sami;

当使用版本的时候, 你的 build_dir 和 cache_dir 必须包含 %version% 标签, add 方法的第二个参数是显示在下拉选项中的标签. 你可使用 addFromTags, setFilter 方法来过滤版本号

php vendor/sami/sami/sami.php update config/config.php

如今你生成的文档目录将会包含每一个版本的说明文档. 用户也可以选择去阅读他想要的版本.

建立主题

如今, 咱们仅仅使用了 default 主题, 可是 Sami 是能够扩展的, 让咱们可以建立本身的主题.

这个 vendor/sami/sami/Sami/Resources/themes 文件夹存储了默认主题. 然而你并不可以把你的主题文件放到这里. Sami 提供了一个方法来添加自定义主题

// config/config.php
    
$templates = $sami['template_dirs'];
$templates[] = __DIR__ . '/../themes/';

$sami['template_dirs'] = $templates;

如今, 咱们在应用程序的根目录存在 themes 文件夹, 建立一个新主题, 咱们须要建立一个文件夹, 而且在文件夹中放置一个 manifest.yml

// themes/laravel/manifest.yml
    
name: laravel
parent: default

咱们的新主题的文件名是 laravel , 他继承于 default 主题属性. 做为示例, 咱们添加一些资源文件, 而且覆盖掉默认模版的一些样式.

添加资源

咱们在建立的主题文件夹中建立一个 css 文件夹, 而且在 css 文件夹中建立一个 laravel.css 文件.

// themes/laravel/css/laravel.css
...  
#api-tree a {
    color: #F4645F;
}

// themes/laravel/manifest.yml
...
static:
    'css/laravel.css': 'css/laravel.css'

这个静态文件配置块, 告诉 Sami , 复制文件到指定的目录, 新的构建目录中会包含新的文件 build/laravel/%version%/css/laravel.css.

// themes/laravel/manifest.yml
...
global:
    'layout/base.twig': 'layout/base.twig'


// themes/laravel/layout/base.twig
...
{% extends 'default/layout/base.twig' %}

{% block head %}
    {{ parent()  }}
    <link rel="stylesheet" href="css/laravel.css" />
{% endblock %}

每次 Sami 想加载 base 布局, 他会使用你主题中定义的文件. 咱们扩展默认的基本布局来保持默认的外观. 而后咱们插入自定义样式到 head 部分. 调用 parent() 函数将保持已经存在的内容在 head 区块中, 而且在 link 标签前输出.

// config/config.php
    
$options = [
    'theme'  => 'laravel',
    //...
];

php vendor/sami/sami/sami.php render config/config.php --force

默认 , Sami 不会在文档未发生任何变化的时候重载. 然而使用 --force 标记会强制输出文件. 在浏览器查看文档页面, 注意下左侧导航的颜色是否是已经改变.

变动标记

// themes/laravel/manifest.yml
    
global:
    'namespaces.twig': 'namespaces.twig'

做为推荐名称, namespaces 文件定义了咱们的命名空间内容是怎么被渲染的.

// themes/laravel/namespaces.twig

{% extends 'default/namespaces.twig' %}
{% from "macros.twig" %}

若是你打开 default/namespaces.twig 页面, 你会发现 Sami 正在使用 macros 来简化扩展模版的进度. 咱们会建立咱们本身的 macros.twig 文件来覆盖默认的标记.

由于 Twig 不支持在 macro 中继承和覆盖重写, 咱们将复制而且粘贴默认的主题 macros 并开始编辑他们

// themes/laravel/macros.twig

{% macro render_classes(classes) -%}
    <div class="container-fluid underlined">
        {% for class in classes %}
            <div class="row">
                <div class="col-md-6">
                    {% if class.isInterface %}
                        <span class="label label-primary">I</span>
                    {% else %}
                        <span class="label label-info">C</span>
                    {% endif %}

                    {{ _self.class_link(class, true) }}
                </div>
                <div class="col-md-6">
                    {{ class.shortdesc|desc(class) }}
                </div>
            </div>
        {% endfor %}
    </div>
{%- endmacro %}

咱们仅仅在这个 macro 中改变了一件事, 就是区分了 Class 和 Interface . Sami 用来重点标识接口可是咱们在每个条目前都标识了一个带颜色的标签.
咱们没有在这个页面改变不少东西. 可是你可能会在你的页面中使用 bootstrap 样式, 让菜单更加响应化或者其余的.
如今, 在从新生成文档以后你会发现你列出了一个 namespace, class 和 interface 都使用标签标识出来了.

概述

在这个文档中, 咱们介绍了一个新的 Symfony 工具来帮助你管理包文档. 你一样能够建立一个独一无二的主题. 你能够找到咱们文档的最终例子 -> Github.若是有什么问题能够给咱们留言. 谢谢