README

Yii 2的API文档生成器

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

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

安装

安装此扩展的首选方法是使用composer。

运行以下命令

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

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

"yiisoft/yii2-apidoc": "~2.1.6"

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

用法

本扩展提供两个命令

• api用于生成类API文档。phpDocumentor被用作基础框架，因此请参阅其指南了解语法。
• 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和GNU make。

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

如果一切顺利，没有错误，PDF将位于output目录中的guide.pdf。

特殊的Markdown语法

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

创建自己的模板

待定

使用模型层

待定