README

Teak是一个CLI工具，用于为PHP项目生成Markdown参考文档（针对WordPress优化）。

它可以生成以下文档

遵循WordPress PHP文档标准的类和全局函数的参考页面
遵循动作和过滤器内联文档标准的WordPress动作和过滤器钩子参考。

当您将其与静态网站生成器结合使用时，可以使用Teak生成的文档创建文档网站。

Teak用于生成Timber的文档，该文档使用Hugo作为静态网站生成器。

安装
CLI用法
DocBlocks
限制
贡献
路线图

安装

您可以使用Composer安装此包

composer require timber/teak --dev

CLI用法

生成类参考

当您传递一个文件夹给类参考生成器时，它将为找到的每个类生成一个单独的Markdown文件。

使用文件夹作为输入

vendor/bin/teak generate:class-reference ./lib/ --output ./docs/reference

这将搜索./lib/中的所有PHP类，并将Markdown文件输出到./docs/reference。

使用单个文件作为输入

vendor/bin/teak generate:class-reference ./lib/Post.php --output ./docs/reference

生成函数参考

函数参考生成器将搜索所有文件中的全局函数，并将它们输出到一个Markdown文件中。

vendor/bin/teak generate:function-reference ./lib/ --output ./docs/

生成钩子参考

钩子参考生成器将搜索所有文件中的WordPress动作或过滤器，并将所有找到的钩子输出到一个Markdown文件中。

vendor/bin/teak generate:hook-reference ./lib --output ./docs/hooks --hook_type=filter
vendor/bin/teak generate:hook-reference ./lib --output ./docs/hooks --hook_type=action

选项

--hook_type – 要查找的钩子类型。必须是filter或action。
--hook_prefix – 钩子前缀（仅选择具有特定前缀的钩子）。

全局CLI选项

显示命令帮助

vendor/bin/teak generate:class-reference -h
vendor/bin/teak generate:function-reference -h
vendor/bin/teak generate:hook-reference -h

文件选项

--file_name – 文件名（将自动追加.md扩展名）
--file_prefix - 文件前缀
--file_title - 文件标题（Markdown文档中的标题1）。仅适用于钩子和函数参考。

Front Matter选项

Teak可以生成Front Matter Blocks，如果您使用生成的Markdown文件通过静态网站生成器生成网站，则将使用这些块。

--front_matter_style – Front Matter类型。目前仅支持"YAML"（如果未提供，将输出标题1而不是Front Matter块）。

DocBlocks

如果您遵循WordPress PHP文档标准，则Teak效果最佳。因为文档以Markdown渲染，所以您可以在DocBlocks中使用Markdown语法。

忽略结构元素

以下条件之一适用时，元素（类、方法、属性）将被忽略

未提供DocBlock
没有@api标签
存在@ignore标签
存在@internal标签
可见性为private（仅适用于方法）

这意味着要为某个类生成Markdown文件，至少需要一个包含@api标签的DocBlock。

/**
 * Class My_Public_Class
 *
 * @api
 */
class My_Public_Class {}

特殊标签

@example

@example标签允许你在DocBlock中添加代码示例，包括代码块。

/**
 * Function summary.
 * 
 * Function description.
 *
 * @api
 * @example
 *
 * Optional text to describe the example
 * 
 * ```php
 * my_method( 'example', false );
 * ```
 *
 * @param string $param1 Description. Default 'value'.
 * @param bool   $param2 Description. Default true.
 */
function my_method( $param1 = 'value', $param2 = true ) {}

数组参数

Teak支持数组参数。

钩子变体

有时你会遇到两个依次出现的钩子，它们基本上做相同的事情，但允许你根据特定条件使钩子仅适用于某些情况。

/**
 * Fires on a specific processing status.
 * 
 * The status can be one of the following: `success`, `error` or `fail`.
 */
do_action( "myplugin/process/status/{$status}" );
do_action( "myplugin/process/status/{$status}/{$action}" );

在这个例子中，你会有一个变量$status和一个$action。第一个动作是在使用特定状态时触发的，第二个动作是在使用特定状态和特定动作时触发的。Teak会将这些钩子变体列在同一个钩子下。因此，你只需要为第一个钩子定义一个DocBlock。

限制

这个编译器并不是phpDocumentor的完整实现。它试图使遵循WordPress PHP文档标准的代码文档更易于阅读，并且更少技术化。尚未考虑所有官方标签。

贡献

欢迎贡献力量。

路线图

CLI：接受文件列表。
支持嵌套数组参数。
添加对内联标签的支持。
添加测试。
优化Markdown文档之间的链接。

timber / teak

维护者

详细信息