README

Yii 2的API文档生成器

此扩展为Yii框架2.0提供API文档生成器。

有关许可证信息，请查看LICENSE文件。

安装

安装此扩展的首选方式是通过composer。

运行以下命令：

composer require --prefer-dist biaoqianwo/yii2-apidoc

上述命令可能在需要解决版本冲突的现有项目上无法正常工作，因此建议手动将包添加到composer.json文件的require部分。

"biaoqianwo/yii2-apidoc": "~2.1.3"

之后运行composer update。如果您想避免更新相关包，也可以运行composer update biaoqianwo/yii2-apidoc cebe/markdown。

用法

此扩展提供两个命令：

• api用于生成类API文档。
• guide用于从Markdown文件（如yii指南）渲染漂亮的HTML页面。

独立类文档的简单用法

vendor/bin/apidoc api source/directory ./output

独立指南文档的简单用法

vendor/bin/apidoc guide source/docs ./output

您可以将它们组合起来在一个地方生成类API和指南文档。

# generate API docs
vendor/bin/apidoc api source/directory ./output
# generate the guide (order is important to allow the guide to link to the apidoc)
vendor/bin/apidoc guide source/docs ./output

默认情况下，将使用bootstrap模板。您可以使用--template=name参数选择不同的模板。目前只有bootstrap模板可用。

您还可以将yii\apidoc\commands\ApiController和GuideController添加到您的控制台应用程序命令映射中，并在您的应用程序控制台应用中运行它们。

从多个来源生成文档

apidoc生成器可以使用多个目录，因此您可以生成应用程序的文档并包含yii框架文档，以便在您的类和框架类之间启用链接。这也允许您的类使用框架扩展时使用@inheritdoc。使用以下命令生成组合API文档：

./vendor/bin/apidoc api ./vendor/biaoqianwo/yii2,. docs/json --exclude="docs,vendor"

这将从./vendor/biaoqianwo/yii2目录和.目录（当前目录）读取源文件（您可以将此替换为您代码的位置，如果它不在当前工作目录中）。

高级用法

以下脚本可用于在不同的目录中生成API文档和指南，以及在多种语言中生成多个指南（如yiiframework.com上所做的那样）。

#!/bin/sh

# set these paths to match your environment
YII_PATH=~/dev/biaoqianwo/yii2
APIDOC_PATH=~/dev/biaoqianwo/yii2/extensions/apidoc
OUTPUT=yii2docs

cd $APIDOC_PATH
./apidoc api $YII_PATH/framework/,$YII_PATH/extensions $OUTPUT/api --guide=../guide-en --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide    $OUTPUT/guide-en --apiDocs=../api --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide-ru $OUTPUT/guide-ru --apiDocs=../api --guidePrefix= --interactive=0
# repeat the last line for more languages

创建指南的PDF

您需要pdflatex和GNU make来完成此操作。

vendor/bin/apidoc guide source/docs ./output --template=pdf
cd ./output
make pdf

如果没有错误运行，PDF将位于output目录中的guide.pdf。

特殊的Markdown语法

我们在API文档中为链接到类有特殊的语法。有关详细信息，请参阅代码风格指南。

创建自己的模板

待定

使用模型层

待定