README

phpDocumentor 3.x 的 Markdown 模板

您是否希望有更简单的方法来生成 PHP 源代码的文档？现在有了！使用 phpDocumentor 和 phpDocumentor-markdown，您可以自动从您的 PHP 源代码中生成 GitHub/GitLab 准备的 Markdown 文档。此模板可用于记录类、接口、特质、常量、属性和方法。

示例

示例文件位于 example 目录。

安装与使用

有关安装 phpDocumentor 的说明，请参阅本指南。
使用说明假定 phpDocumentor 是 phpDocumentor 3.x 二进制文件。

手动运行

# Run phpDocumentor with --template argument pointed to this directory's markdown template
phpDocumentor --directory=src --target=docs --template=<PATH TO THIS REPOSITORY/themes/markdown>

使用 Composer

通过 Composer 安装

# Require this package. You probably want it as a dev dependency
composer require --dev saggre/phpdocumentor-markdown

通过 Composer 安装后手动运行

# Run phpDocumentor with --template argument pointed to markdown template inside vendor directory
phpDocumentor --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"

添加 Composer 辅助脚本

将此脚本添加到您的 composer.json 中，然后运行 composer create-docs 以生成文档。

"scripts": {
    "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'"
},

使用 PhpDocumentor XML 配置

将模板元素添加到您的 PhpDocumentor XML 配置中，然后运行 phpDocumentor 以生成文档。

<phpdocumentor>
    <!-- Specify template element inside phpdocumentor -->
    <template name="./vendor/linchpin/phpdocumentor-markdown/themes/markdown"/>
</phpdocumentor>

您还可以查看用于生成此存储库示例文档的配置文件以获取完整的示例。

运行测试

# Clone the repository
git clone git@github.com:linchpin/phpDocumentor-markdown.git

# Go to the cloned repository
cd phpDocumentor-markdown

# Install dependencies
composer install

# Set up PHPUnit configuration
cp phpunit.xml.dist phpunit.xml

# Run PHPUnit in project root directory
composer run-tests

贡献

使用 PSR-12 编码风格
由于 Twig 扩展尚不支持 phpDocumentor3，因此使用 Twig 宏创建自定义功能。
测试套件使用 Twig 扩展来测试 Twig 宏功能。
请查看 \phpDocumentor\Descriptor\ProjectDescriptor 以获取生成文档所用的数据结构。

linchpin / phpdocumentor-markdown-template

维护者

详细信息