摘要：原文地址為方法類(lèi)函數(shù)生成文檔已經(jīng)成為了程序員的習(xí)慣所以需要知道通過(guò)源代碼生成獨(dú)立的文檔本文中我會(huì)介紹一款新的文檔生成工具什么是是插入到類(lèi)接口方法屬性頂部的多行注釋為了闡明這個(gè)我們看下中的代碼片段開(kāi)始于結(jié)束于每行之間使用當(dāng)定義一個(gè)類(lèi)屬性或者

原文地址: Generating PHP Documentation with Sami

為方法, 類(lèi), 函數(shù)生成文檔已經(jīng)成為了程序員的習(xí)慣, 所以需要知道通過(guò)源代碼生成獨(dú)立的文檔. 本文中我會(huì)介紹 Sami, 一款 新的 API 文檔生成工具.

DocBlock 是插入到 類(lèi), 接口, 方法, 屬性頂部的多行注釋, 為了闡明這個(gè), 我們看下 Laravel 中的代碼片段

abstract class Manager
{
  /**
   * The application instance.
   *
   * @var IlluminateFoundationApplication
   */
  protected $app;
  

  /**
   * Create a new manager instance.
   *
   * @param IlluminateFoundationApplication $app
   * @return void
   */
  public function __construct($app)
  {
    $this->app = $app;
  }
}

DocBlock 開(kāi)始于 /**, 結(jié)束于 */, 每行之間使用 *. 當(dāng)定義一個(gè)類(lèi)屬性或者方法的時(shí)候, 我們會(huì)寫(xiě)一個(gè)描述或者多個(gè)注釋來(lái)描述這個(gè)功能. 在這些示例中 @param 和@var 會(huì)被用到. 你可以訪問(wèn) phpDocumentor 官方網(wǎng)站來(lái)熟悉每個(gè)標(biāo)簽的用法.

世界上充滿(mǎn)許多文檔生成器, 但是最好的一個(gè)是 phpDocumentor, 我喜歡 Sami 的主要原因是能夠使用github 上版本控制的文檔, 并且可以使用 Twig 來(lái)生成模版

有兩種方式來(lái)安裝 Sami. 第一個(gè)是 下載 Phar 壓縮包并且使用php來(lái)運(yùn)行

php sami.phar

第二個(gè)方式是通過(guò) Composer. 你可以運(yùn)行 composer require sami/sami:3.0.* 命令來(lái)添加 sami 包到你的項(xiàng)目中.

php vendor/sami/sami/sami.php

本示例中, 我會(huì)生成 Laravel Illuminate package 的文檔

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

現(xiàn)在我們的文件結(jié)構(gòu)如下所示:

docs/
vendor/
composer.json

update 命令用來(lái)更新文檔, 下面是使用方法:

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

config.php 文件來(lái)描述你的文檔結(jié)構(gòu)并且告知如何渲染輸出.

配置文件必須返回 SamiSami 實(shí)例, 他接受 SymfonyComponentFinderFinder 實(shí)例和一系列的選擇項(xiàng).

// config/config.php
    
$dir = __DIR__ . "/../docs";

$iterator = SymfonyComponentFinderFinder::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 SamiSami($iterator, $options);

return $sami;

$dir 變量保存源代碼的路徑. $iterator 獲取所有文件并且選擇 *.php 并且排除 build 和test 目錄. $options 變量里邊的內(nèi)容比較顯而易見(jiàn). theme設(shè)置成 default , 我們稍后講如何建立自己的主題. build_dir 保存輸出文件. cache_dir 放置 Twig 緩存, title 是生成文檔的標(biāo)題

現(xiàn)在, 打開(kāi)命令行并運(yùn)行如下命令

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

命令執(zhí)行完之后, 你可以運(yùn)行內(nèi)置的PHP服務(wù)器來(lái)查看文檔, 運(yùn)行 php -S localhost:8000 -t build/, 并且訪問(wèn) http://localhost:8000/laravel/ 來(lái)查看運(yùn)行結(jié)果

我提到了使用 Sami 的一個(gè)重要原因就是他的版本控制. options["versions"] 參數(shù)接受一個(gè) SamiVersionGitVersionCollection 實(shí)例來(lái)保存你的 Git 庫(kù)配置. 如下, 讓我們創(chuàng)建 5.0 和4.2 分支的文檔.

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

$iterator = SymfonyComponentFinderFinder::create()
    ->files()
    ->name("*.php")
    ->in($dir);

$versions = SamiVersionGitVersionCollection::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 SamiSami($iterator, $options);

return $sami;

當(dāng)使用版本的時(shí)候, 你的 build_dir 和 cache_dir 必須包含 %version% 標(biāo)簽, add 方法的第二個(gè)參數(shù)是顯示在下拉選項(xiàng)中的標(biāo)簽. 你可以使用 addFromTags, setFilter 方法來(lái)過(guò)濾版本號(hào)

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

現(xiàn)在你生成的文檔目錄將會(huì)包含每個(gè)版本的說(shuō)明文檔. 用戶(hù)也能夠選擇去閱讀他想要的版本.

現(xiàn)在, 我們僅僅使用了 default 主題, 但是 Sami 是可以擴(kuò)展的, 讓我們能夠創(chuàng)建自己的主題.

這個(gè) vendor/sami/sami/Sami/Resources/themes 文件夾存儲(chǔ)了默認(rèn)主題. 然而你并不能夠把你的主題文件放到這里. Sami 提供了一個(gè)方法來(lái)添加自定義主題

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

$sami["template_dirs"] = $templates;

現(xiàn)在, 我們?cè)趹?yīng)用程序的根目錄存在 themes 文件夾, 創(chuàng)建一個(gè)新主題, 我們需要?jiǎng)?chuàng)建一個(gè)文件夾, 并且在文件夾中放置一個(gè) manifest.yml

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

我們的新主題的文件名是 laravel , 他繼承于 default 主題屬性. 作為示例, 我們添加一些資源文件, 并且覆蓋掉默認(rèn)模版的一些樣式.

我們?cè)趧?chuàng)建的主題文件夾中創(chuàng)建一個(gè) css 文件夾, 并且在 css 文件夾中創(chuàng)建一個(gè) laravel.css 文件.

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

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

這個(gè)靜態(tài)文件配置塊, 告訴 Sami , 復(fù)制文件到指定的目錄, 新的構(gòu)建目錄中會(huì)包含新的文件 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()  }}
    
{% endblock %}

每次 Sami 想加載 base 布局, 他會(huì)使用你主題中定義的文件. 我們擴(kuò)展默認(rèn)的基本布局來(lái)保持默認(rèn)的外觀. 然后我們插入自定義樣式到 head 部分. 調(diào)用 parent() 函數(shù)將保持已經(jīng)存在的內(nèi)容在 head 區(qū)塊中, 并且在 link 標(biāo)簽前輸出.

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

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

默認(rèn) , Sami 不會(huì)在文檔未發(fā)生任何變化的時(shí)候重載. 然而使用 --force 標(biāo)記會(huì)強(qiáng)制輸出文件. 在瀏覽器查看文檔頁(yè)面, 注意下左側(cè)導(dǎo)航的顏色是不是已經(jīng)改變.

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

作為推薦名稱(chēng), namespaces 文件定義了我們的命名空間內(nèi)容是怎么被渲染的.

// themes/laravel/namespaces.twig

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

如果你打開(kāi) default/namespaces.twig 頁(yè)面, 你會(huì)發(fā)現(xiàn) Sami 正在使用 macros 來(lái)簡(jiǎn)化擴(kuò)展模版的進(jìn)度. 我們會(huì)創(chuàng)建我們自己的 macros.twig 文件來(lái)覆蓋默認(rèn)的標(biāo)記.

因?yàn)?Twig 不支持在 macro 中繼承和覆蓋重寫(xiě), 我們將復(fù)制并且粘貼默認(rèn)的主題 macros 并開(kāi)始編輯他們

// themes/laravel/macros.twig

{% macro render_classes(classes) -%}
    

        {% for class in classes %}
            

                

                    {% if class.isInterface %}
                        I
                    {% else %}
                        C
                    {% endif %}

                    {{ _self.class_link(class, true) }}
                
                

                    {{ class.shortdesc|desc(class) }}
                
            
        {% endfor %}
    
{%- endmacro %}

我們僅僅在這個(gè) macro 中改變了一件事, 就是區(qū)分了 Class 和 Interface . Sami 用來(lái)重點(diǎn)標(biāo)識(shí)接口但是我們?cè)诿恳粋€(gè)條目前都標(biāo)識(shí)了一個(gè)帶顏色的標(biāo)簽.
我們沒(méi)有在這個(gè)頁(yè)面改變很多東西. 但是你可能會(huì)在你的頁(yè)面中使用 bootstrap 樣式, 讓菜單更加響應(yīng)化或者其他的.
現(xiàn)在, 在重新生成文檔之后你會(huì)發(fā)現(xiàn)你列出了一個(gè) namespace, class 和 interface 都使用標(biāo)簽標(biāo)識(shí)出來(lái)了.

在這個(gè)文檔中, 我們介紹了一個(gè)新的 Symfony 工具來(lái)幫助你管理包文檔. 你同樣可以創(chuàng)建一個(gè)獨(dú)一無(wú)二的主題. 你可以找到我們文檔的最終例子 -> Github.如果有什么問(wèn)題可以給我們留言. 謝謝