README

Yii 2的API文档生成器

注意：在原始更新后，此存储库将被删除。

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

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

安装

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

运行以下命令：

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

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

"autoxloo/yii2-apidoc": "~2.1.0"

之后运行 composer update。如果您想避免更新相关包，也可以运行 composer update autoxloo/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/yiisoft/yii2,. docs/json --exclude="docs,vendor"

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

高级使用

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

#!/bin/sh

# set these paths to match your environment
YII_PATH=~/dev/yiisoft/yii2
APIDOC_PATH=~/dev/yiisoft/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和GNUmake。

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

如果一切运行正常，没有错误，PDF将位于output目录中，文件名为guide.pdf。

特殊的Markdown语法

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

创建自己的模板

待定

使用模型层

待定