原文地址：GeneratingPHPDocumentationwithSami为方法、类、函数生成文档已经成为程序员的习惯，所以你需要知道如何通过源码生成独立的文档。在本文中，我将介绍一种新的API文档生成工具Sami。什么是文档块？DocBlock是插入在类、接口、方法或属性顶部的多行注释。为了说明这一点，让我们看一下Laravel中的代码片段。abstractclassManager{/***应用实例。**@var\Illuminate\Foundation\Application*/protected$app;/***创建一个新的管理器实例。**@param\Illuminate\Foundation\Application$app*@returnvoid*/publicfunction__construct($app){$this->app=$app;}}DocBlock以/**开始，以*/结束，每行之间使用*。在定义一个类的属性或者方法的时候，我们会写一个描述或者多个注释来描述这个Function。在这些示例中，将使用@param和@var。你可以访问phpDocumentor官网来熟悉一下各个标签的用法。API文档生成器世界上有很多文档生成器，但最好的是phpDocumentor，我喜欢Sami的主要原因是我可以使用github上的版本控制文档，并且可以使用Twig生成模板。安装Sami有两种安装Sami的方法。第一种是下载Phar归档文件并使用php运行phpsami.phar第二种方式是通过Composer。你可以运行composerrequiresami/sami:3.0.*命令将sami包添加到你的项目.phpvendor/sami/sami/sami.php复制Laravel的文档在这个例子中，我将生成LaravelIlluminate包的文档gitclonegit@github.com:laravel/framework.gitdocs现在我们的文件结构如下：docs/vendor/composer.jsonupdate该命令用于更新文档，下面是如何更新使用它：phpvendor/sami/sami/sami.php更新config/config.phpconfig.php文件来描述您的文档结构并告诉如何呈现输出。Configuration/配置文件必须返回一个Sami\Sami实例，它接受一个Symfony\Component\Finder\Finder实例和一系列选项。//config/config.php$dir=__DIR__。'/../文档'；$iterator=Symfony\Component\Finder\Finder::create()->files()->name('*.php')->exclude('build')->exclude('tests')->in($目录);$options=['theme'=>'default','title'=>'LaravelAPIDocumentation','build_dir'=>__DIR__.'/../build/laravel','cache_dir'=>__DIR__。'/../cache/laravel',];$sami=newSami\Sami($iterator,$options);return$sami;$dir变量保存源码的路径。$iterator获取所有文件并选择*.php并排除构建和测试目录。$options变量的内容更明显。以后如何构建自己的主题。build_dir保存输出文件。cache_dir是用来存放Twig缓存的，title是生成文档的标题现在，打开命令行，运行如下命令phpvendor/sami/sami/sami.phpupdateconfig/config.php命令执行后，你可以运行内置的PHPServer查看文档，运行php-Slocalhost:8000-tbuild/，访问http://localhost:8000/laravel/查看运行结果使用我提到的Git版本控制使用Sami的重要原因之一就是他的版本控制。options['versions']参数接受一个Sami\Version\GitVersionCollection实例来保存你的Git存储库配置。下面，让我们为5.0和4.2分支创建文档。$目录=__DIR__。'/../docs/src';$ite??rator=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'=>'LaravelAPIDocumentation','build_dir'=>__DIR__。'/../build/laravel/%version%','cache_dir'=>__DIR__。'/../cache/laravel/%version%',];$sami=newSami\Sami($iterat或者，$options);返回$sami；使用version时，你的build_dir和cache_dir必须包含%version%标签，add方法的第二个参数是下拉选项中显示的标签。您可以使用addFromTags、setFilter方法来过滤版本号phpvendor/sami/sami/sami.phpupdateconfig/config.php现在您生成的文档目录将包含每个版本的文档。用户也可以选择阅读自己喜欢的版本。创建主题现在，我们只使用了默认主题，但Sami是可扩展的，允许我们创建自己的主题。vendor/sami/sami/Sami/Resources/themes文件夹存储默认主题。但是，你不能把你的主题文件放在这里。Sami提供了一种添加自定义主题的方法//config/config.php$templates=$sami['template_dirs'];$templates[]=__DIR__。'/../themes/';$sami['template_dirs']=$templates;现在，我们在应用程序的根目录下有了themes文件夹，要创建一个新的主题，我们需要创建一个文件夹，并在/themes/laravel/manifest.yml文件夹中放置一个manifest.yml/name:laravelparent:default我们新主题的文件名为laravel，它继承了defaulttheme属性。例如，我们添加一些资源文件并覆盖默认模板的一些样式。添加资源我们在创建的theme文件夹下创建一个css文件夹，在css文件夹下创建一个laravel.css文件//themes/laravel/css/laravel.css...#api-treea{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'%}{%blockhead%}{{parent()}}
