资讯专栏INFORMATION COLUMN

[译] 使用 Sami 生成 PHP 文档

banana_pi / 3557人阅读

摘要:原文地址为方法类函数生成文档已经成为了程序员的习惯所以需要知道通过源代码生成独立的文档本文中我会介绍一款新的文档生成工具什么是是插入到类接口方法属性顶部的多行注释为了阐明这个我们看下中的代码片段开始于结束于每行之间使用当定义一个类属性或者

原文地址: Generating PHP Documentation with Sami

为方法, 类, 函数生成文档已经成为了程序员的习惯, 所以需要知道通过源代码生成独立的文档. 本文中我会介绍 Sami, 一款 新的 API 文档生成工具.

什么是 DocBlock?

DocBlock 是插入到 类, 接口, 方法, 属性顶部的多行注释, 为了阐明这个, 我们看下 Laravel 中的代码片段

</>复制代码

  1. abstract class Manager
  2. {
  3. /**
  4. * The application instance.
  5. *
  6. * @var IlluminateFoundationApplication
  7. */
  8. protected $app;
  9. /**
  10. * Create a new manager instance.
  11. *
  12. * @param IlluminateFoundationApplication $app
  13. * @return void
  14. */
  15. public function __construct($app)
  16. {
  17. $this->app = $app;
  18. }
  19. }

DocBlock 开始于 /**, 结束于 */, 每行之间使用 *. 当定义一个类属性或者方法的时候, 我们会写一个描述或者多个注释来描述这个功能. 在这些示例中 @param 和@var 会被用到. 你可以访问 phpDocumentor 官方网站来熟悉每个标签的用法.

API 文档生成器

世界上充满许多文档生成器, 但是最好的一个是 phpDocumentor, 我喜欢 Sami 的主要原因是能够使用github 上版本控制的文档, 并且可以使用 Twig 来生成模版

安装 Sami

有两种方式来安装 Sami. 第一个是 下载 Phar 压缩包并且使用php来运行

</>复制代码

  1. php sami.phar

第二个方式是通过 Composer. 你可以运行 composer require sami/sami:3.0.* 命令来添加 sami 包到你的项目中.

</>复制代码

  1. php vendor/sami/sami/sami.php

复制 Laravel’s 文档

本示例中, 我会生成 Laravel Illuminate package 的文档

</>复制代码

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

现在我们的文件结构如下所示:

</>复制代码

  1. docs/
  2. vendor/
  3. composer.json

update 命令用来更新文档, 下面是使用方法:

</>复制代码

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

config.php 文件来描述你的文档结构并且告知如何渲染输出.

Configuration / 配置

配置文件必须返回 SamiSami 实例, 他接受 SymfonyComponentFinderFinder 实例和一系列的选择项.

</>复制代码

  1. // config/config.php
  2. $dir = __DIR__ . "/../docs";
  3. $iterator = SymfonyComponentFinderFinder::create()
  4. ->files()
  5. ->name("*.php")
  6. ->exclude("build")
  7. ->exclude("tests")
  8. ->in($dir);
  9. $options = [
  10. "theme" => "default",
  11. "title" => "Laravel API Documentation",
  12. "build_dir" => __DIR__ . "/../build/laravel",
  13. "cache_dir" => __DIR__ . "/../cache/laravel",
  14. ];
  15. $sami = new SamiSami($iterator, $options);
  16. return $sami;

$dir 变量保存源代码的路径. $iterator 获取所有文件并且选择 *.php 并且排除 buildtest 目录. $options 变量里边的内容比较显而易见. theme设置成 default , 我们稍后讲如何建立自己的主题. build_dir 保存输出文件. cache_dir 放置 Twig 缓存, title 是生成文档的标题

现在, 打开命令行并运行如下命令

</>复制代码

  1. 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"] 参数接受一个 SamiVersionGitVersionCollection 实例来保存你的 Git 库配置. 如下, 让我们创建 5.04.2 分支的文档.

</>复制代码

  1. $dir = __DIR__ . "/../docs/src";
  2. $iterator = SymfonyComponentFinderFinder::create()
  3. ->files()
  4. ->name("*.php")
  5. ->in($dir);
  6. $versions = SamiVersionGitVersionCollection::create($dir)
  7. ->add("5.0", "Master")
  8. ->add("4.2", "4.2");
  9. $options = [
  10. "theme" => "default",
  11. "versions" => $versions,
  12. "title" => "Laravel API Documentation",
  13. "build_dir" => __DIR__ . "/../build/laravel/%version%",
  14. "cache_dir" => __DIR__ . "/../cache/laravel/%version%",
  15. ];
  16. $sami = new SamiSami($iterator, $options);
  17. return $sami;

当使用版本的时候, 你的 build_dircache_dir 必须包含 %version% 标签, add 方法的第二个参数是显示在下拉选项中的标签. 你可以使用 addFromTags, setFilter 方法来过滤版本号

</>复制代码

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

现在你生成的文档目录将会包含每个版本的说明文档. 用户也能够选择去阅读他想要的版本.

创建主题

现在, 我们仅仅使用了 default 主题, 但是 Sami 是可以扩展的, 让我们能够创建自己的主题.

这个 vendor/sami/sami/Sami/Resources/themes 文件夹存储了默认主题. 然而你并不能够把你的主题文件放到这里. Sami 提供了一个方法来添加自定义主题

</>复制代码

  1. // config/config.php
  2. $templates = $sami["template_dirs"];
  3. $templates[] = __DIR__ . "/../themes/";
  4. $sami["template_dirs"] = $templates;

现在, 我们在应用程序的根目录存在 themes 文件夹, 创建一个新主题, 我们需要创建一个文件夹, 并且在文件夹中放置一个 manifest.yml

</>复制代码

  1. // themes/laravel/manifest.yml
  2. name: laravel
  3. parent: default

我们的新主题的文件名是 laravel , 他继承于 default 主题属性. 作为示例, 我们添加一些资源文件, 并且覆盖掉默认模版的一些样式.

添加资源

我们在创建的主题文件夹中创建一个 css 文件夹, 并且在 css 文件夹中创建一个 laravel.css 文件.

</>复制代码

  1. // themes/laravel/css/laravel.css
  2. ...
  3. #api-tree a {
  4. color: #F4645F;
  5. }

</>复制代码

  1. // themes/laravel/manifest.yml
  2. ...
  3. static:
  4. "css/laravel.css": "css/laravel.css"

这个静态文件配置块, 告诉 Sami , 复制文件到指定的目录, 新的构建目录中会包含新的文件 build/laravel/%version%/css/laravel.css.

</>复制代码

  1. // themes/laravel/manifest.yml
  2. ...
  3. global:
  4. "layout/base.twig": "layout/base.twig"
  5. // themes/laravel/layout/base.twig
  6. ...
  7. {% extends "default/layout/base.twig" %}
  8. {% block head %}
  9. {{ parent() }}
  10. {% endblock %}

每次 Sami 想加载 base 布局, 他会使用你主题中定义的文件. 我们扩展默认的基本布局来保持默认的外观. 然后我们插入自定义样式到 head 部分. 调用 parent() 函数将保持已经存在的内容在 head 区块中, 并且在 link 标签前输出.

</>复制代码

  1. // config/config.php
  2. $options = [
  3. "theme" => "laravel",
  4. //...
  5. ];

</>复制代码

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

默认 , Sami 不会在文档未发生任何变化的时候重载. 然而使用 --force 标记会强制输出文件. 在浏览器查看文档页面, 注意下左侧导航的颜色是不是已经改变.

变更标记

</>复制代码

  1. // themes/laravel/manifest.yml
  2. global:
  3. "namespaces.twig": "namespaces.twig"

作为推荐名称, namespaces 文件定义了我们的命名空间内容是怎么被渲染的.

</>复制代码

  1. // themes/laravel/namespaces.twig
  2. {% extends "default/namespaces.twig" %}
  3. {% from "macros.twig" %}

如果你打开 default/namespaces.twig 页面, 你会发现 Sami 正在使用 macros 来简化扩展模版的进度. 我们会创建我们自己的 macros.twig 文件来覆盖默认的标记.

因为 Twig 不支持在 macro 中继承和覆盖重写, 我们将复制并且粘贴默认的主题 macros 并开始编辑他们

</>复制代码

  1. // themes/laravel/macros.twig
  2. {% macro render_classes(classes) -%}
  3. {% for class in classes %}
  4. {% if class.isInterface %}
  5. I
  6. {% else %}
  7. C
  8. {% endif %}
  9. {{ _self.class_link(class, true) }}
  10. {{ class.shortdesc|desc(class) }}
  11. {% endfor %}
  12. {%- endmacro %}

我们仅仅在这个 macro 中改变了一件事, 就是区分了 ClassInterface . Sami 用来重点标识接口但是我们在每一个条目前都标识了一个带颜色的标签.
我们没有在这个页面改变很多东西. 但是你可能会在你的页面中使用 bootstrap 样式, 让菜单更加响应化或者其他的.
现在, 在重新生成文档之后你会发现你列出了一个 namespace, class 和 interface 都使用标签标识出来了.

概述

在这个文档中, 我们介绍了一个新的 Symfony 工具来帮助你管理包文档. 你同样可以创建一个独一无二的主题. 你可以找到我们文档的最终例子 -> Github.如果有什么问题可以给我们留言. 谢谢

文章版权归作者所有,未经允许请勿转载,若此文章存在违规行为,您可以联系管理员删除。

转载请注明本文地址:https://www.ucloud.cn/yun/25747.html

相关文章

  • PHP:40+开发工具推荐

    摘要:今天,就为开发者介绍个方便的工具。对开发者来说,是一个非常有用的工具,它提供了超过个有用的函数。该工具检查输入源代码和报告任何违反给定的标准。框架是一个开发的工具。它侧重于安全性和性能,绝对是最安全的开发框架之一。 PHP是为Web开发设计的服务器脚本语言,但也是一种通用的编程语言。超过2.4亿个索引域使用PHP,包括很多重要的网站,例如Facebook、Digg和WordPress。...

    dreambei 评论0 收藏0
  • [] 给PHP开发者的PHP源码-第一部分-源码结构

    摘要:另一个说明我叫它做宏。你可以为函数定义写一个宏事实上,就是这么做的,但我们会在后面的文章中深入了解这个。我想说的是,宏允许在预处理编译时使用更简单的代码。或者说头文件定义了在文件中可以被其他文件看到的函数,包括预处理宏。 文章来自:http://www.hoohack.me/2016/02/04/phps-source-code-for-php-developers-ch 原文:ht...

    wenzi 评论0 收藏0
  • 】CodeIgniter HMVC模块扩展使用文档

    摘要:和模块分离类似,模块扩展使得模块变得可便携的。模块化意味着模块化。但是,模块扩展更进一步,它允许这些模块互相通信。 CodeIgniter HMVC扩展说明 原文地址:Modular Extensions - HMVC 模块扩展——HMVC 模块扩展让CodeIgniter框架模块化。模块是一组独立的组件(通常有模型、控制器和视图),它们被分类在应用模块的子文件夹中,并且能够直接拖到其...

    teren 评论0 收藏0
  • PHP中的随机性——你觉得自己幸运吗?

    摘要:本文分析了生成用于加密的随机数的相关问题。没有提供一种简单的机制来生成密码学上强壮的随机数,但是通过引入几个函数来解决了这个问题。呢缺省情况下,不提供强壮的随机数发生器。如果你想要使用可靠的随机数据源,如你在本文所见,建议尽快使用和 本文分析了生成用于加密的随机数的相关问题。 PHP 5没有提供一种简单的机制来生成密码学上强壮的随机数,但是PHP 7通过引入几个CSPRNG函数来解决了...

    邹强 评论0 收藏0
  • PHP中的随机性——你觉得自己幸运吗?

    摘要:本文分析了生成用于加密的随机数的相关问题。没有提供一种简单的机制来生成密码学上强壮的随机数,但是通过引入几个函数来解决了这个问题。呢缺省情况下,不提供强壮的随机数发生器。如果你想要使用可靠的随机数据源,如你在本文所见,建议尽快使用和 本文分析了生成用于加密的随机数的相关问题。 PHP 5没有提供一种简单的机制来生成密码学上强壮的随机数,但是PHP 7通过引入几个CSPRNG函数来解决了...

    Eric 评论0 收藏0

发表评论

0条评论

最新活动
阅读需要支付1元查看
<