[譯] 使用 Sami 生成 PHP 文檔

時間 2019-12-06

標籤使用 sami 生成 php 文檔欄目 PHP 简体版

原文原文鏈接

原文地址: Generating PHP Documentation with Samiphp

爲方法, 類, 函數生成文檔已經成爲了程序員的習慣, 因此須要知道經過源代碼生成獨立的文檔. 本文中我會介紹 Sami, 一款新的 API 文檔生成工具. css

什麼是 DocBlock?

DocBlock 是插入到類, 接口, 方法, 屬性頂部的多行註釋, 爲了闡明這個, 咱們看下 Laravel 中的代碼片斷html

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 官方網站來熟悉每一個標籤的用法.laravel

API 文檔生成器

世界上充滿許多文檔生成器, 可是最好的一個是 phpDocumentor, 我喜歡 Sami 的主要緣由是可以使用github 上版本控制的文檔, 而且可使用 Twig 來生成模版git

安裝 Sami

有兩種方式來安裝 Sami. 第一個是下載 Phar 壓縮包而且使用php來運行程序員

php sami.phar

第二個方式是經過 Composer. 你能夠運行 composer require sami/sami:3.0.* 命令來添加 sami 包到你的項目中.github

php vendor/sami/sami/sami.php

複製 Laravel’s 文檔

本示例中, 我會生成 Laravel Illuminate package 的文檔json

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

如今咱們的文件結構以下所示:bootstrap

docs/
vendor/
composer.json

update 命令用來更新文檔, 下面是使用方法:api

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 都使用標籤標識出來了.