Codeigniter项目使用phpDocumentor生成api文档
前言
运行环境:
-
vagrant 2.2.4
-
virtualbox 6.0
-
box
bento/ubuntu-16.04(Apache 2.4.18 + Mysql 5.7.26 + PHP 5.6.40)
phpDocumentor 2 是一个尽可能的通过你的PHP源码来生成文档的工具。
通过 Codeigniter项目applicaiton下控制器和模型 2个文件夹的源码来生成 api文档
vagrant@vagrant:~$ phpdoc -V
phpDocumentor version v2.9.0
我是通过 phar 方式进行安装
wget https://www.phpdoc.org/phpDocumentor.phar # 下载phpDocumentor.phar文件
# php phpDocumentor.phar -V
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc #将文件移入到/usr/local/bin下，并重命名为phpdoc,在所有目录下，都可以运行 phpdoc命令了，即全局命令
phpdoc -h # 输出帮助信息
phpdoc -V # 输出版本信息
phpdoc template:list # 列出使用的模板
使用
简单的使用 phpDocumentor 是使用命令行参数(-d 一个目录，-f 一个文件)来提供一个输入点和告诉它你喜欢放的文件夹(-t)来输出你的文档。
例如:
$ phpdoc -d ./src -t ./docs/api
上面的案列会扫描 在src 和它子文件夹下的所有文件，执行分析和生成一个包含文档的网站在docs/api下。如果你没有指定-t选项，文档的输出将会写入到一个子文件夹为output文件夹中。
命令:
codeignniter$: phpdoc -d "application/controllers,application/models" -t ./docs/api
在docs/api可以看到生成的文档
通过配置文件进行配置
phpdoc.dist.xml 配置文件内容
<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
<title>Codeigniter</title>
<parser>
<target>docs/api</target>
</parser>
<files>
<directory>application/controllers</directory>
<directory>application/models</directory>
</files>
<transformations>
<template name="responsive-twig" />
<target>docs/api</target>
</transformations>
</phpdoc>
命令:
codeigniter$: phpdoc -c phpdoc.dist.xml
我安裝apigen網站的教程，通過 composer的方式安裝 apigen 庫，然後生成基於Codeigniter 3.1.10項目的Api 文檔
composer require apigen/apigen --dev
composer.json 中require-dev顯示的 "apigen/apigen": "^4.1"
單個源文件夾src,輸出目錄docs
vendor/bin/apigen generate -s application/controllers --destination docs2
將應用的
vendor/bin/apigen generate -s application/controllers,application/models,application/core,application/helpers --destination apigendoc
apigen generate help
vagrant@vagrant:/var/www/html/codeigniter310$ vendor/bin/apigen generate --help
Usage:
generate [options]
Options:
-s, --source=SOURCE Dirs or files documentation is generated for. (multiple values allowed)
-d, --destination=DESTINATION Target dir for documentation.
--access-levels=ACCESS-LEVELS Access levels of included method and properties. [default: ["public","protected"]] (multiple values allowed)
--annotation-groups=ANNOTATION-GROUPS Generate page with elements with specific annotation.
--base-url=BASE-URL Base url used for sitemap (useful for public doc).
--config=CONFIG Custom path to apigen.neon config file. [default: "/var/www/html/mainpowers3/apigen.neon"]
--google-cse-id=GOOGLE-CSE-ID Custom google search engine id (for search box).
--google-analytics=GOOGLE-ANALYTICS Google Analytics tracking code.
--debug Turn on debug mode.
--deprecated Generate documentation for elements marked as @deprecated
--download Add link to ZIP archive of documentation.
--extensions=EXTENSIONS Scanned file extensions. [default: ["php"]] (multiple values allowed)
--exclude=EXCLUDE Directories and files matching this mask will not be parsed (e.g. */tests/*). (multiple values allowed)
--groups=GROUPS The way elements are grouped in menu. [default: "auto"]
--charset=CHARSET Charset of scanned files. (multiple values allowed)
--main=MAIN Elements with this name prefix will be first in tree.
--internal Include elements marked as @internal.
--php Generate documentation for PHP internal classes.
--skip-doc-path=SKIP-DOC-PATH Files matching this mask will be included in class tree, but will not create a link to their documentation. (multiple values allowed)
--no-source-code Do not generate highlighted source code for elements.
--template-theme=TEMPLATE-THEME ApiGen template theme name. [default: "default"]
--template-config=TEMPLATE-CONFIG Your own template config, has higher priority templateTheme.
--title=TITLE Title of generated documentation.
--todo Generate documentation for elements marked as @todo.
--tree Generate tree view of classes, interfaces, traits and exceptions.
-h, --help Display this help message.
-q, --quiet Do not output any message.
-V, --version Display this application version.
Help:
Generate API documentation
