pradosoft/apigen

此包已被废弃且不再维护。未建议替代包。

PHP 源代码 API 生成器 - Prado 分支

维护者

详细信息

github.com/pradosoft/ApiGen

主页

源代码

安装: 2,912

依赖项: 1

建议者: 0

安全: 0

星标: 0

关注者: 8

分支: 319

v4.2.0-RC1 2017-04-03 22:01 UTC

Requires

Requires (Dev)

Conflicts

MIT 357dd07724d9789bcaa4ec5709a7a1a4a2a0cdc2

generatordocumentationphpdocapi

This package is auto-updated.

Last update: 2022-04-04 09:18:10 UTC

README

Build Status Build status Code Coverage Downloads Latest stable

只需查看 CakePHP 框架 或 Doctrine ORM API。

注意！ 这是 4.2 分支，ApiGen 的最终 4.x 系列。项目正在进行重构（master 上的 5.x 系列）。请将任何针对 4.2.x 版本的 PR 提交给 4.2 分支。

要求

  • PHP 5.5+

安装

使用 composer 在您的项目中作为开发依赖项安装

composer require --dev apigen/apigen

或者，如果您想全局安装

composer global require --dev apigen/apigen

使用方法

运行 ApiGen，并指定源和目标选项

vendor/bin/apigen generate -s ./src -d ./docs

要省略 CLI 选项，只需在您的项目根目录中创建 apigen.yaml 或 apigen.neon 文件即可

source:
    - ./src

destination: ./docs

要获取所有可用选项，包括描述和默认值，只需运行

vendor/bin/apigen generate --help

文档

DocBlock 注释

本节提供了 ApiGen 支持的 PHP DocBlock 注释（标签） 列表

  • @author - 记录关联元素的作者。
  • @copyright - 记录关联元素的版权信息。
  • @deprected - 指示关联元素已过时，可在未来版本中删除。
  • @internal - 表示关联元素是此应用程序或库的内部元素，默认情况下隐藏。
  • @license - 指示关联元素的适用许可证。
  • @link - 指示关联元素与网站页面之间的关联。
  • @method - 允许类知道哪些“魔法”方法是可以调用的。
  • @package - 将关联元素分类到逻辑分组或子分类中。
  • @param - 记录函数或方法的单个参数。
  • @property - 允许类知道哪些“魔法”属性存在。
  • @return - 记录函数或方法的返回值。
  • @see - 指示关联元素与网站或其他元素之间的引用。
  • @subpackage - 将关联元素分类到逻辑分组或子分类中。
  • @throws - 指示关联元素是否可能抛出特定类型的异常。
  • @usedby 指示一个与单个关联元素关联的“从”引用。
  • @uses - 指示对（和从）单个关联元素的引用。

配置

本节提供了有关所有可用的配置选项的信息，这些选项可以包含在配置文件（apigen.yml 或 apigen.neon）中。

最小配置

最小配置文件

# apigen.neon.dist
# This is minimal configuration for ApiGen.
source: [src]           # directory(-ies) to scan PHP files from
destination: docs       # destination directory to generate API docs in

注意！配置文件与generate命令的CLI选项匹配。唯一的区别是，在配置文件中定义这些选项时，必须使用camelCase格式（例如，CLI选项--annotation-groups变为配置参数annotationGroups）。

参考配置

包含所有可用和受支持配置选项的参考配置文件。

# apigen.neon.dist
# This is reference configuration for ApiGen. It contains all of the available
# and supported configuration options, together with their default values.
# source options
source: [src]                       # Source directory(-ies) to build API docs for
                                    # (array)
extensions: [php]                   # A list of file extension to include when
                                    # scanning source dir (array)
accessLevels: [public, protected]   # Access levels of methods and properties
                                    # to include (array)
annotationGroups: [todo, deprecated]# Annotation Groups to include (array)
internal: false                     # Set to `true` to include @internal in API
                                    # docs (boolean)
#main: 'SomePrefix'                 # Elements with this name prefix will be
                                    # first in the tree (string)
php: false                          # Set to `true` to generate docs for PHP
                                    # internal classes (boolean)
noSourceCode: false                 # Set to `true` to NOT generate highlighted
                                    # source code for elements (boolean)

# destination / generated docs options
destination: doc                    # Destination directory for API docs (string)
exclude: tests                      # A blob pattern to exclude from API docs
                                    # generation (string (blob))
overwrite: true                     # Overwrite destination directory by
                                    # default (boolean)
title: "ApiGen Docs"                # Title of generated API docs (string)
baseUrl: http://apigen.org/api      # Base URL for generated API docs (string (URL))
templateConfig: path/to/config.neon # path to template configuration (string (path))

# templates parameters
googleAnalytics: 123                # Google Analytics tracking code (string)
googleCseId: 456                    # Google Custom Search Engine ID (string)
download: true                      # show a link to download API docs ZIP
                                    # archive in the API docs (boolean)

# debug
debug: false                        # set to true to enable debug (boolean)

CLI命令

本节提供有关所有可用CLI命令及其选项的信息。

主要ApiGen命令

要获取可用命令列表，请使用apigen list。要获取特定命令的帮助，请使用apigen help，例如。

$ apigen help generate

生成

generate命令是主要命令，用于生成API文档。该命令依赖于传递CLI选项或从配置文件读取数据。

generate命令接受以下选项列表

选项 描述
--source (-s) 用于生成API文档的源目录（-ies）。允许多个值。
--destination (-d) API文档的目标目录。
--access-levels 包含在API文档中的方法和属性的可访问级别[选项：public、protected、private]。默认：["public","protected"]。
--annotation-groups 生成具有特定注解的元素页面。
--config 自定义ApiGen配置文件路径。默认：./apigen.neon
--google-cse-id 自定义Google搜索引擎ID（用于搜索框）。
--base-url 基本URL（用于Sitemap / 搜索框）。
--google-analytics 要在生成的API文档中包含的Google Analytics跟踪代码。
--debug 开启调试模式（打印低级别解析器的详细信息）。在调试/开发期间非常有用。
--download 传递此选项以在API文档中包含生成ZIP存档的链接。
--extensions 要扫描的文件扩展名列表。允许多个值。默认：["php"]。
--exclude 匹配提供的掩码的目录或文件将被排除（例如，*/tests/*）。允许多个值。
--groups 在菜单中定义元素分组[选项：namespaces、packages]。默认：namespaces。
--main 具有提供的主要名称前缀的元素将首先在树中。
--internal 包含标记为@internal的元素。
--php 为PHP内部类生成文档。
--no-source-code 不要为元素生成高亮显示的源代码。
--template-theme ApiGen模板主题名称。[默认："default"]。
--template-config 指定自己的模板配置（此设置将覆盖--template-theme）。
--title API文档的自定义标题。
--tree 生成类、接口、特性和异常的树视图。
--deprecated 已弃用，仅用于BC
--todo 已弃用，仅用于BC
--charset 已弃用，仅用于BC
--skip-doc-path 已弃用，仅用于BC
--overwrite (-o) 强制覆盖目标目录。
--help (-h) 显示所有或特定命令的帮助信息。
--quiet (-q) 不输出任何信息。
--version (-V) 显示ApiGen的版本。

主题

为了启用自定义主题，您必须在运行apigen generate时提供--theme-config CLI选项或在ApiGen配置文件中添加themeConfig配置选项

themeConfig: path/to/theme/config.neon # path to theme's config file

贡献

请参阅CONTRIBUTING以获取详细信息。

测试

要运行测试

$ vendor/bin/phpunit

获取支持！

  • #apigen on irc.freenode.net - 加入我们的聊天，我们有蛋糕。
  • GitHub Issues - 有问题？请告诉我们！
  • Roadmaps - 想要贡献？加入我们！