README

Yii 2的API文档生成器

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

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

安装

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

运行以下命令

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

上述命令可能无法在现有项目中运行，因为需要解决版本冲突，因此建议您手动将包添加到composer.json文件的要求部分

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

然后运行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文档中链接到类时有特殊的语法。有关详细信息，请参阅代码风格指南。

创建自己的模板

待定

使用模型层

待定