README

PHP（Docco的移植）注解源代码生成器。此库受到了Phrocco的启发。

Pinocchio爬取项目中的源代码文件，并自动生成注解源HTML页面，这些页面既可以作为自文档化的项目，也可以作为类似API的文档。

主要优势

易于使用
几乎无要求（仅PHP >= 5.3.6）
可配置和可定制
使项目实现自文档化

安装

您可以使用Composer安装Pinocchio。您很可能将Pinocchio用作开发库，而不是需要用于项目使用的库，因此您可能希望将其用作composer.json文件中的dev要求，如下所示

{
    "require-dev": {
        "ncuesta/pinocchio": "dev-master"
    }
}

一旦这样设置，您就可以通过提供--dev标志来安装它

$ composer install --dev

如果Composer抱怨稳定性问题，您可能需要在composer.json文件中添加一个minimum-stability键，如下所示

{
    "require-dev": {
        "ncuesta/pinocchio": "dev-master"
    },
    "minimum-stability": "dev"
}

使用方法

通过Composer安装后，您可以直接从命令行界面使用Pinocchio，如下所示。请注意，vendor/bin/pinocchio是Pinocchio可执行文件的路径，而vendor/bin是Composer默认安装任何供应商二进制文件的目录。如果您已更改此路径，请确保您是从特定的路径运行Pinocchio。

因此，运行

$ php vendor/bin/pinocchio

将会爬取位于./src目录下的任何源代码文件，并在./output目录下生成相应的注解源文件。以下是对此行为的进一步自定义。

配置

Pinocchio可以通过多种方式进行配置。您可以在运行脚本时提供配置选项，从位于项目根目录的配置文件中获取设置，或者两者的组合。

选项源考虑的顺序是

命令行参数
配置文件值
默认值

配置选项

以下是一个所有配置选项及其可接受值的列表

source (string)：要爬取源代码的源代码目录的路径。
output (string)：要保存生成文件的输出目录的路径。
template (string)：用于每个源代码文件的模板的路径。
css (array)：要用于模板中的一组CSS文件。
ignore (string)：一个正则表达式，如果匹配源目录内的任何路径，将排除该路径从爬取的文件中。
silent (boolean)：一个值，表示是否应该静默日志或输出内容。
logger (字符串)：用作日志记录器类的完全限定类名。这个类应当实现 \Pinocchio\Logger\LoggerInterface。
logger_opts (数组)：在初始化日志记录器时要提供的选项集。请注意，默认的日志记录器类不考虑任何选项。
skip_index (布尔值)：如果为 true，则不会生成索引文件。否则，将在 output 目录中创建一个 index.html 文件，其中包含对不同的文件的链接，如 index_template 模板所示。
index_template (字符串)：用于索引文件的模板的路径。仅在 skip_index 为 true 时适用。
index_title (字符串)：要添加到索引文件中的标题。

作为参数的配置

在运行 Pinocchio 时，您可以传递作为配置选项考虑的参数。例如

$ php vendor/bin/pinocchio --source src --output annotated-source

将告诉 Pinocchio，已将 source 选项设置为 src，将 output 设置为 annotated-source。

配置文件

如果发现名为 pinocchio.json 的文件在您调用 Pinocchio 的目录中（即您的项目根目录），则它将用作配置源。例如

{
    "source":   "lib",
    "output":   "doc",
    "template": "path/to/some/template.php",
    "css":      ["stylesheet_1.css", "path/to/stylesheet_2.css"],
    "ignore":   "/ignore\s+me\s+regex/i",
    "silent":   true
}

默认值

所有配置值都有一个合理的默认值，因此您无需进行配置。以下是不同配置选项的所有默认值列表

source：'src'。
output：'output'。
template：基于 Docco 模板的内置模板。
css：基于 Docco 样式的内置样式表。
ignore：'/^\./'。默认情况下忽略点文件。
silent：false。默认情况下记录所有内容。不必担心，它并不那么啰嗦。
logger：'\Pinocchio\Logger\StandardLogger'。默认类，如果您想指定一个完全限定的类，则可以这样做。请注意，它应实现 \Pinocchio\Logger\LoggerInterface。
logger_opts：[]（一个空数组）。默认情况下不向日志记录器提供任何选项。
skip_index：false。
index_template：一个内置模板，它简单地将链接到每个解析的源文件。
index_title：'Source files'。

贡献

Pinocchio 是一个开源项目，因此欢迎任何合作、建议等。对于这些事项中的任何一项，请使用问题或创建拉取请求。

许可证

Pinocchio 在 MIT 许可证下发布。以下是一些无聊的法律条款

Copyright (c) 2012 José Nahuel Cuesta Luengo

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ncuesta / pinocchio

维护者

详情