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

原文地址: Generating PHP Documentation with Sami

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

DocBlock 是插入到 類, 接口, 方法, 屬性頂部的多行注釋, 為了闡明這個, 我們看下 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)定義一個類屬性或者方法的時候, 我們會寫一個描述或者多個注釋來描述這個功能. 在這些示例中 @param 和@var 會被用到. 你可以訪問 phpDocumentor 官方網(wǎng)站來熟悉每個標簽的用法.

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

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

php sami.phar

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

php vendor/sami/sami/sami.php

本示例中, 我會生成 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 實例, 他接受 SymfonyComponentFinderFinder 實例和一系列的選擇項.

// 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 是生成文檔的標題

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

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

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

我提到了使用 Sami 的一個重要原因就是他的版本控制. options["versions"] 參數(shù)接受一個 SamiVersionGitVersionCollection 實例來保存你的 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)使用版本的時候, 你的 build_dir 和 cache_dir 必須包含 %version% 標簽, add 方法的第二個參數(shù)是顯示在下拉選項中的標簽. 你可以使用 addFromTags, setFilter 方法來過濾版本號

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

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

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

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

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

$sami["template_dirs"] = $templates;

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

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

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

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

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

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

這個靜態(tài)文件配置塊, 告訴 Sami , 復(fù)制文件到指定的目錄, 新的構(gòu)建目錄中會包含新的文件 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 布局, 他會使用你主題中定義的文件. 我們擴展默認的基本布局來保持默認的外觀. 然后我們插入自定義樣式到 head 部分. 調(diào)用 parent() 函數(shù)將保持已經(jīng)存在的內(nèi)容在 head 區(qū)塊中, 并且在 link 標簽前輸出.

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

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

默認 , Sami 不會在文檔未發(fā)生任何變化的時候重載. 然而使用 --force 標記會強制輸出文件. 在瀏覽器查看文檔頁面, 注意下左側(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 頁面, 你會發(fā)現(xiàn) Sami 正在使用 macros 來簡化擴展模版的進度. 我們會創(chuàng)建我們自己的 macros.twig 文件來覆蓋默認的標記.

因為 Twig 不支持在 macro 中繼承和覆蓋重寫, 我們將復(fù)制并且粘貼默認的主題 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 %}

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

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