Codeigniter项目使用phpDocumentor生成api文档

前言

运行环境:

  1. vagrant 2.2.4

  2. virtualbox 6.0

  3. box bento/ubuntu-16.04 (Apache 2.4.18 + Mysql 5.7.26 + PHP 5.6.40)

  4. phpDocumentor

phpDocumentor 2 是一个尽可能的通过你的PHP源码来生成文档的工具。

通过 Codeigniter项目applicaiton下控制器和模型 2个文件夹的源码来生成 api文档

1
2
vagrant@vagrant:~$ phpdoc -V
phpDocumentor version v2.9.0

我是通过 phar 方式进行安装

1
2
3
4
5
6
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)来输出你的文档。

例如:

1
$ phpdoc -d ./src -t ./docs/api

上面的案列会扫描 在src 和它子文件夹下的所有文件,执行分析和生成一个包含文档的网站在docs/api下。如果你没有指定-t选项,文档的输出将会写入到一个子文件夹为output文件夹中。

命令:

1
codeignniter$: phpdoc -d "application/controllers,application/models" -t ./docs/api

docs/api可以看到生成的文档

通过配置文件进行配置

phpdoc.dist.xml 配置文件内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?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>

命令:

1
codeigniter$: phpdoc -c phpdoc.dist.xml

apigen

我安裝apigen網站的教程,通過 composer的方式安裝 apigen 庫,然後生成基於Codeigniter 3.1.10項目的Api 文檔

1
composer require apigen/apigen --dev

composer.json 中require-dev顯示的 "apigen/apigen": "^4.1"

單個源文件夾src,輸出目錄docs

1
vendor/bin/apigen generate -s application/controllers --destination docs2

將應用的

1
vendor/bin/apigen generate -s application/controllers,application/models,application/core,application/helpers --destination apigendoc

apigen generate help

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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

References