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

原文地址: Generating PHP Documentation with Sami

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

DocBlock 是插入到 類, 接口, 方法, 屬性頂部的多行注釋, 為了闡明這個(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 開始于 /**, 結(jié)束于 */, 每行之間使用 *. 當(dāng)定義一個(gè)類屬性或者方法的時(shí)候, 我們會(huì)寫一個(gè)描述或者多個(gè)注釋來描述這個(gè)功能. 在這些示例中 @param 和@var 會(huì)被用到. 你可以訪問 phpDocumentor 官方網(wǎng)站來熟悉每個(gè)標(biāo)簽的用法.

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

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

php sami.phar

第二個(gè)方式是通過 Composer. 你可以運(yùn)行 composer require sami/sami:3.0.* 命令來添加 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 命令用來更新文檔, 下面是使用方法:

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

config.php 文件來描述你的文檔結(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)容比較顯而易見. theme設(shè)置成 default , 我們稍后講如何建立自己的主題. build_dir 保存輸出文件. cache_dir 放置 Twig 緩存, title 是生成文檔的標(biāo)題

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

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

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

我提到了使用 Sami 的一個(gè)重要原因就是他的版本控制. options["versions"] 參數(shù)接受一個(gè) SamiVersionGitVersionCollection 實(shí)例來保存你的 Git 庫配置. 如下, 讓我們創(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 方法來過濾版本號(hào)

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

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

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

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

// 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)的基本布局來保持默認(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)制輸出文件. 在瀏覽器查看文檔頁面, 注意下左側(cè)導(dǎo)航的顏色是不是已經(jīng)改變.

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

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

// themes/laravel/namespaces.twig

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

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

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

// 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 用來重點(diǎn)標(biāo)識(shí)接口但是我們?cè)诿恳粋€(gè)條目前都標(biāo)識(shí)了一個(gè)帶顏色的標(biāo)簽.
我們沒有在這個(gè)頁面改變很多東西. 但是你可能會(huì)在你的頁面中使用 bootstrap 樣式, 讓菜單更加響應(yīng)化或者其他的.
現(xiàn)在, 在重新生成文檔之后你會(huì)發(fā)現(xiàn)你列出了一個(gè) namespace, class 和 interface 都使用標(biāo)簽標(biāo)識(shí)出來了.

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