README

为 Yii 2 生成 API 文档

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

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

安装

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

运行以下命令：

composer require --prefer-dist yiisoft/yii2-apidoc:"~3.0.6"

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

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

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

使用方法

此扩展在 /vendor/bin 创建可执行文件。如果您不想使用完整路径（即 /vendor/bin/apidoc），请将目录更改为该目录，并使用以下示例中的可执行文件名。

此扩展提供两个命令：

1) api 生成类 API 文档。使用 phpDocumentor 作为基础框架，请参阅其指南了解语法。

help api 命令的输出（即 apidoc help api）

DESCRIPTION

Renders API documentation files


USAGE

apidoc api <sourceDirs> <targetDir> [...options...]

- sourceDirs (required): array

- targetDir (required): string


OPTIONS

--appconfig: string
  custom application configuration file path.
  If not set, default application configuration is used.

--color: boolean, 0 or 1
  whether to enable ANSI color in the output.
  If not set, ANSI color will only be enabled for terminals that support it.

--exclude: string|array
  files to exclude.

--guide: string
  url to where the guide files are located

--guide-prefix: string (defaults to 'guide-')
  prefix to prepend to all guide file names.

--help, -h: boolean, 0 or 1 (defaults to 0)
  whether to display help information about current command.

--interactive: boolean, 0 or 1 (defaults to 1)
  whether to run the command interactively.

--page-title: string

--repo-url: string
  Repository url (e.g. "https://github.com/yiisoft/yii2"). Optional, used for resolving relative links
  within a repository (e.g. "[docs/guide/README.md](docs/guide/README.md)"). If you don't have such links you can
  skip this. Otherwise, skipping this will cause generation of broken links because they will be not resolved and
  left as is.

--silent-exit-on-exception: boolean, 0 or 1
  if true - script finish with `ExitCode::OK` in case of exception.
  false - `ExitCode::UNSPECIFIED_ERROR`.
  Default: `YII_ENV_TEST`

--template: string (defaults to 'bootstrap')
  template to use for rendering

2) guide 从 markdown 文件（如 yii 指南）生成漂亮的 HTML 页面。

help guide 命令的输出（即 apidoc help guide）

DESCRIPTION

Renders API documentation files


USAGE

apidoc guide <sourceDirs> <targetDir> [...options...]

- sourceDirs (required): array

- targetDir (required): string


OPTIONS

--api-docs: string
  path or URL to the api docs to allow links to classes and properties/methods.

--appconfig: string
  custom application configuration file path.
  If not set, default application configuration is used.

--color: boolean, 0 or 1
  whether to enable ANSI color in the output.
  If not set, ANSI color will only be enabled for terminals that support it.

--exclude: string|array
  files to exclude.

--guide-prefix: string (defaults to 'guide-')
  prefix to prepend to all output file names generated for the guide.

--help, -h: boolean, 0 or 1 (defaults to 0)
  whether to display help information about current command.

--interactive: boolean, 0 or 1 (defaults to 1)
  whether to run the command interactively.

--page-title: string

--silent-exit-on-exception: boolean, 0 or 1
  if true - script finish with `ExitCode::OK` in case of exception.
  false - `ExitCode::UNSPECIFIED_ERROR`.
  Default: `YII_ENV_TEST`

--template: string (defaults to 'bootstrap')
  template to use for rendering

独立类文档的简单使用

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

独立指南文档的简单使用

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

请注意，为了生成合适的索引文件，必须存在包含对指南部分的链接的 README.md 文件。此类文件的示例可以在 yii2 存储库 中找到。

您可以将它们结合起来，在同一个地方生成类 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.
• Pygments.
• GNU make。

生成

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

如果一切顺利运行且无错误，PDF将位于output目录下的guide.pdf。

特殊的Markdown语法

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

创建自己的模板

待定

使用模型层

待定